concept-components.md 3.55 KB
Newer Older
1 2 3
Components
==========

Larry Ullman committed
4
Components are the main building blocks of Yii applications. Components are instances of [[yii\base\Component]],
Larry Ullman committed
5 6 7 8 9 10 11
or an extended class. The three main features that components provide to other classes are:

* [Properties](concept-properties.md)
* [Events](concept-events.md)
* [Behaviors](concept-behaviors.md),
 
Separately and combined, these features make Yii classes much more customizable and easier to use. For example, the included [[yii\jui\DatePicker|date picker widget]], a user interface component, can be used in a [view](structure-view.md)
12
to generate an interactive date picker:
13

14 15 16 17 18 19 20 21 22 23 24
```php
use yii\jui\DatePicker;

echo DatePicker::widget([
    'language' => 'ru',
    'name'  => 'country',
    'clientOptions' => [
        'dateFormat' => 'yy-mm-dd',
    ],
]);
```
25

Larry Ullman committed
26 27 28
The widget's properties are easily writable because the class extends [[yii\base\Component]].

While components are very powerful, they are a bit heavier than normal objects, due to the fact that
Larry Ullman committed
29
it takes extra memory and CPU time to support [event](concept-events.md) and [behavior](concept-behaviors.md) functionality in particular.
30
If your components do not need these two features, you may consider extending your component class from
Larry Ullman committed
31
[[yii\base\Object]] instead of [[yii\base\Component]]. Doing so will make your components as efficient as normal PHP objects,
Larry Ullman committed
32
but with added support for [properties](concept-properties.md).
33

34 35 36
When extending your class from [[yii\base\Component]] or [[yii\base\Object]], it is recommended that you follow
these conventions:

Larry Ullman committed
37
- If you override the constructor, specify a `$config` parameter as the constructor's *last* parameter, and then pass this parameter
38
  to the parent constructor.
Larry Ullman committed
39 40
- Always call the parent constructor *at the end* of your overriding constructor.
- If you override the [[yii\base\Object::init()]] method, make sure you call the parent implementation of `init` *at the beginning* of your `init` method.
41

Larry Ullman committed
42
For example:
43 44

```php
45 46 47 48 49
namespace yii\components\MyClass;

use yii\base\Object;

class MyClass extends Object
50
{
51 52 53
    public $prop1;
    public $prop2;

54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69
    public function __construct($param1, $param2, $config = [])
    {
        // ... initialization before configuration is applied

        parent::__construct($config);
    }

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

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

AbrahamGreyson committed
70
Following these guidelines will make your components [configurable](concept-configurations.md) when they are created. For example:
71 72

```php
73 74 75 76 77 78 79
$component = new MyClass(1, 2, ['prop1' => 3, 'prop2' => 4]);
// alternatively
$component = \Yii::createObject([
    'class' => MyClass::className(),
    'prop1' => 3,
    'prop2' => 4,
], [1, 2]);
80
```
81

Larry Ullman committed
82
> Info: While the approach of calling [[Yii::createObject()]] looks more complicated, it is more powerful because it is implemented on top of a [dependency injection container](concept-di-container.md).
Qiang Xue committed
83 84
  

85 86
The [[yii\base\Object]] class enforces the following object lifecycle:

Larry Ullman committed
87 88 89
1. Pre-initialization within the constructor. You can set default property values here.
2. Object configuration via `$config`. The configuration may overwrite the default values set within the constructor.
3. Post-initialization within [[yii\base\Object::init()|init()]]. You may override this method to perform sanity checks and normalization of the properties.
90 91
4. Object method calls.

Larry Ullman committed
92 93
The first three steps all happen within the object's constructor. This means that once you get a class instance (i.e., an object),
that object has already been initialized to a proper, reliable state.