basic-properties.md 4.62 KB
Newer Older
1 2 3 4 5 6 7
Basic concepts of Yii
=====================


Component and Object
--------------------

Aris Karageorgos committed
8
Classes of the Yii framework usually extend from one of the two base classes [[yii\base\Object]] or [[yii\base\Component]].
Carsten Brandt committed
9
These classes provide useful features that are added automatically to all classes extending from them.
10

Aris Karageorgos committed
11
The [[yii\base\Object|Object]] class provides the [configuration and property feature](../api/base/Object.md).
12 13
The [[yii\base\Component|Component]] class extends from [[yii\base\Object|Object]] and adds
[event handling](events.md) and [behaviors](behaviors.md).
Carsten Brandt committed
14

15 16
[[yii\base\Object|Object]] is usually used for classes that represent basic data structures while
[[yii\base\Component|Component]] is used for application components and other classes that implement higher logic.
17 18 19 20 21


Object Configuration
--------------------

22 23
The [[yii\base\Object|Object]] class introduces a uniform way of configuring objects. Any descendant class
of [[yii\base\Object|Object]] should declare its constructor (if needed) in the following way so that
24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44
it can be properly configured:

```php
class MyClass extends \yii\base\Object
{
    public function __construct($param1, $param2, $config = [])
    {
        // ... initialization before configuration is applied

        parent::__construct($config);
    }

    public function init()
    {
        parent::init();

        // ... initialization after configuration is applied
    }
}
```

Aris Karageorgos committed
45 46 47
In the above example, the last parameter of the constructor must take a configuration array
which contains name-value pairs that will be used to initialize the object's properties at the end of the constructor.
You can override the `init()` method to do initialization work after the configuration is applied.
48

Aris Karageorgos committed
49
By following this convention, you will be able to create and configure new objects
50 51 52 53 54 55 56
using a configuration array like the following:

```php
$object = Yii::createObject([
    'class' => 'MyClass',
    'property1' => 'abc',
    'property2' => 'cde',
Qiang Xue committed
57
], [$param1, $param2]);
58 59 60
```


Carsten Brandt committed
61 62
Path Aliases
------------
63 64

Yii 2.0 expands the usage of path aliases to both file/directory paths and URLs. An alias
Aris Karageorgos committed
65 66
must start with an `@` symbol so that it can be differentiated from file/directory paths and URLs.
For example, the alias `@yii` refers to the Yii installation directory while `@web` contains the base URL for the currently running web application. Path aliases are supported in most places in the Yii core code. For example, `FileCache::cachePath` can accept both a path alias and a normal directory path.
67

Aris Karageorgos committed
68
Path aliases are also closely related to class namespaces. It is recommended that a path
it3rmit committed
69
alias should be defined for each root namespace so that Yii's class autoloader can be used without
70 71 72 73 74
any further configuration. For example, because `@yii` refers to the Yii installation directory,
a class like `yii\web\Request` can be autoloaded by Yii. If you use a third party library
such as Zend Framework, you may define a path alias `@Zend` which refers to its installation
directory and Yii will be able to autoload any class in this library.

75 76 77 78 79 80 81 82
The following aliases are predefined by the core framework:

- `@yii` - framework directory.
- `@app` - base path of currently running application.
- `@runtime` - runtime directory.
- `@vendor` - Composer vendor directory.
- `@webroot` - web root directory of currently running web application.
- `@web` - base URL of currently running web application.
83 84 85 86

Autoloading
-----------

Aris Karageorgos committed
87
All classes, interfaces and traits are loaded automatically at the moment they are used. There's no need to use `include` or `require`. It is true for Composer-loaded packages as well as Yii extensions.
88

Aris Karageorgos committed
89 90
Yii's autoloader works according to [PSR-4](https://github.com/php-fig/fig-standards/blob/master/proposed/psr-4-autoloader/psr-4-autoloader.md).
That means namespaces, classes, interfaces and traits must correspond to file system paths and file names accordinly, except for root namespace paths that are defined by an alias.
91

Aris Karageorgos committed
92
For example, if the standard alias `@app` refers to `/var/www/example.com/` then `\app\models\User` will be loaded from `/var/www/example.com/models/User.php`.
93

Aris Karageorgos committed
94
Custom aliases may be added using the following code:
95 96

```php
Carsten Brandt committed
97
Yii::setAlias('@shared', realpath('~/src/shared'));
98 99
```

Aris Karageorgos committed
100
Additional autoloaders may be registered using PHP's standard `spl_autoload_register`.
101 102 103 104

Helper classes
--------------

Aris Karageorgos committed
105
Helper classes typically contain static methods only and are used as follows:
106 107 108 109 110 111 112 113 114 115 116 117 118

```php
use \yii\helpers\Html;
echo Html::encode('Test > test');
```

There are several classes provided by framework:

- ArrayHelper
- Console
- FileHelper
- Html
- HtmlPurifier
119
- Image
120 121 122 123 124
- Inflector
- Json
- Markdown
- Security
- StringHelper
125
- Url
Qiang Xue committed
126
- VarDumper