concept-configurations.md 9.96 KB
Newer Older
1 2
Configurations
==============
3

4 5
Configurations are widely used in Yii for creating new objects or initializing existing objects.
They usually include the class names of the objects being created and a list of initial values
6 7 8
that should be assigned to object [properties](concept-properties.md). They may also include a list of
handlers that should be attached to the object [events](concept-events.md), and/or a list of
[behaviors](concept-behaviors.md) that should be attached to the objects.
Qiang Xue committed
9

10
In the following, a configuration is used to create and initialize a DB connection:
Qiang Xue committed
11 12

```php
13 14 15 16 17 18 19 20 21
$config = [
    'class' => 'yii\db\Connection',
    'dsn' => 'mysql:host=127.0.0.1;dbname=demo',
    'username' => 'root',
    'password' => '',
    'charset' => 'utf8',
];

$db = Yii::createObject($config);
Qiang Xue committed
22 23
```

24 25 26
The [[Yii::createObject()]] method takes a configuration and creates an object based on the class name
specified in the configuration. When the object is being instantiated, the rest of the configuration
will be used to initialize the object properties, event handlers and/or behaviors.
Qiang Xue committed
27

28 29
If you already have an object, you may use [[Yii::configure()]] to initialize the object properties with
a configuration, like the following,
Qiang Xue committed
30 31

```php
32
Yii::configure($object, $config);
Qiang Xue committed
33 34
```

35
Note that in this case, the configuration should not contain the `class` element.
Qiang Xue committed
36

37

Qiang Xue committed
38
## Configuration Format <a name="configuration-format"></a>
Larry Ullman committed
39

40
The format of a configuration can be formally described as follows,
Larry Ullman committed
41 42

```php
43 44 45 46 47 48
[
    'class' => 'ClassName',
    'propertyName' => 'propertyValue',
    'on eventName' => $eventHandler,
    'as behaviorName' => $behaviorConfig,
]
Larry Ullman committed
49 50
```

51
where
52

53 54
* The `class` element specifies a fully qualified class name for the object being created.
* The `propertyName` elements specify the property initial values. The keys are the property names, and the
55
  values are the corresponding initial values. Only public member variables and [properties](concept-properties.md)
56
  defined by getters/setters can be configured.
57
* The `on eventName` elements specify what handlers should be attached to the object [events](concept-events.md).
58
  Notice that the array keys are formed by prefixing event names with `on `. Please refer to
59
  the [Events](concept-events.md) section for supported event handler formats.
60
* And the `as behaviorName` elements specify what [behaviors](concept-behaviors.md) should be attached to the object.
61 62
  Notice that the array keys are formed by prefixing behavior names with `on `. `$behaviorConfig` represents
  the configuration for creating a behavior, like a normal configuration as we are describing here.
63

64
Below is an example showing a configuration with property initial values, event handlers and behaviors:
65 66

```php
67 68 69 70 71 72 73 74 75
[
    'class' => 'app\components\SearchEngine',
    'apiKey' => 'xxxxxxxx',
    'on search' => function ($event) {
        Yii::info("Keyword searched: " . $event->keyword);
    },
    'as indexer' => [
        'class' => 'app\components\IndexerBehavior',
        // ... property init values ...
76
    ],
77
]
78 79 80
```


Qiang Xue committed
81
## Using Configurations <a name="using-configurations"></a>
82

83 84
Configurations are used in many places in Yii. At the beginning of this section, we have shown how to use
create an object according to a configuration by using [[Yii::createObject()]]. In this subsection, we will
85
describe application configurations and widget configurations - two major usages of configurations.
86

87

Qiang Xue committed
88
### Application Configurations <a name="application-configurations"></a>
89 90 91 92 93 94

Configuration for an [application](structure-applications.md) is probably one of the most complex configurations.
This is because the [[yii\web\Application|application]] class has a lot of configurable properties and events.
More importantly, its [[yii\web\Application::components|components]] property can receive an array of configurations
for creating components that are registered through the application. The following is an abstract from the application
configuration file for the [basic application template](start-basic.md).
95 96

```php
97 98
$config = [
    'id' => 'basic',
99
    'basePath' => dirname(__DIR__),
100
    'extensions' => require(__DIR__ . '/../vendor/yiisoft/extensions.php'),
101
    'components' => [
102 103 104 105 106 107
        'cache' => [
            'class' => 'yii\caching\FileCache',
        ],
        'mail' => [
            'class' => 'yii\swiftmailer\Mailer',
        ],
108
        'log' => [
109
            'class' => 'yii\log\Dispatcher',
110 111 112 113 114 115 116
            'traceLevel' => YII_DEBUG ? 3 : 0,
            'targets' => [
                [
                    'class' => 'yii\log\FileTarget',
                ],
            ],
        ],
117 118 119 120 121 122 123
        'db' => [
            'class' => 'yii\db\Connection',
            'dsn' => 'mysql:host=localhost;dbname=stay2',
            'username' => 'root',
            'password' => '',
            'charset' => 'utf8',
        ],
124
    ],
Alexander Makarov committed
125
];
126 127
```

128 129
The configuration does not have a `class` key. This is because it is used as follows in
an [entry script](structure-entry-scripts.md), where the class name is already given,
Larry Ullman committed
130

131 132 133
```php
(new yii\web\Application($config))->run();
```
134

135
For more details about configuring the `components` property of an application can be found
136
in the [Applications](structure-applications.md) section and the [Service Locator](concept-service-locator.md) section.
137 138


Qiang Xue committed
139
### Widget Configurations <a name="widget-configurations"></a>
140

141 142 143
When using [widgets](structure-widgets.md), you often need to use configurations to customize the widget properties.
Both of the [[yii\base\Widget::widget()]] and [[yii\base\Widget::beginWidget()]] methods can be used to create
a widget. They take a configuration array, like the following,
144 145

```php
146 147 148 149 150 151 152 153
use yii\widgets\Menu;

echo Menu::widget([
    'activateItems' => false,
    'items' => [
        ['label' => 'Home', 'url' => ['site/index']],
        ['label' => 'Products', 'url' => ['product/index']],
        ['label' => 'Login', 'url' => ['site/login'], 'visible' => Yii::$app->user->isGuest],
Qiang Xue committed
154 155
    ],
]);
156 157
```

158 159
The above code creates a `Menu` widget and initializes its `activeItems` property to be false.
The `items` property is also configured with menu items to be displayed.
Qiang Xue committed
160

161
Note that because the class name is already given, the configuration array should NOT have the `class` key.
Qiang Xue committed
162 163


Qiang Xue committed
164
## Configuration Files <a name="configuration-files"></a>
Qiang Xue committed
165

166
When a configuration is very complex, a common practice is to store it in one or multiple PHP files, known as
Qiang Xue committed
167
*configuration files*. A configuration file returns a PHP array representing the configuration.
168
For example, you may keep an application configuration in a file named `web.php`, like the following,
Qiang Xue committed
169 170 171

```php
return [
172 173 174 175
    'id' => 'basic',
    'basePath' => dirname(__DIR__),
    'extensions' => require(__DIR__ . '/../vendor/yiisoft/extensions.php'),
    'components' => require(__DIR__ . '/components.php'),
Qiang Xue committed
176 177
];
```
178

179 180
Because the `components` configuration is complex too, you store it in a separate file called `components.php`
and "require" this file in `web.php` as shown above. The content of `components.php` is as follows,
181 182 183

```php
return [
184 185 186 187 188 189 190 191 192 193 194 195
    'cache' => [
        'class' => 'yii\caching\FileCache',
    ],
    'mail' => [
        'class' => 'yii\swiftmailer\Mailer',
    ],
    'log' => [
        'class' => 'yii\log\Dispatcher',
        'traceLevel' => YII_DEBUG ? 3 : 0,
        'targets' => [
            [
                'class' => 'yii\log\FileTarget',
196 197 198
            ],
        ],
    ],
199 200 201 202 203 204 205
    'db' => [
        'class' => 'yii\db\Connection',
        'dsn' => 'mysql:host=localhost;dbname=stay2',
        'username' => 'root',
        'password' => '',
        'charset' => 'utf8',
    ],
206 207 208
];
```

Qiang Xue committed
209
To get a configuration stored in a configuration file, simply "require" it, like the following:
210 211 212 213 214 215 216

```php
$config = require('path/to/web.php');
(new yii\web\Application($config))->run();
```


Qiang Xue committed
217
## Default Configurations <a name="default-configurations"></a>
218

219
The [[Yii::createObject()]] method is implemented based on a [dependency injection container](concept-di-container.md).
220 221 222 223 224 225 226 227 228 229 230 231 232 233 234
It allows you specify a set of the so-called *default configurations* which will be applied to ANY instances of
the specified classes when they are being created using [[Yii::createObject()]]. The default configurations
can be specified by calling `Yii::$container->set()` in the [bootstrapping](runtime-bootstrapping.md) code.

For example, if you want to customize [[yii\widgets\LinkPager]] so that ALL link pagers will show at most 5 page buttons
(the default value is 10), you may use the following code to achieve this goal,

```php
\Yii::$container->set('yii\widgets\LinkPager', [
    'maxButtonCount' => 5,
]);
```

Without using default configurations, you would have to configure `maxButtonCount` in every place where you use
link pagers.
235 236


Qiang Xue committed
237
## Environment Constants <a name="environment-constants"></a>
238 239 240 241

Configurations often vary according to the environment in which an application runs. For example,
in development environment, you may want to use a database named `mydb_dev`, while on production server
you may want to use the `mydb_prod` database. To facilitate switching environments, Yii provides a constant
Qiang Xue committed
242
named `YII_ENV` that you may define in the [entry script](structure-entry-scripts.md) of your application.
243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270
For example,

```php
defined('YII_ENV') or define('YII_ENV', 'dev');
```

You may define `YII_ENV` as one of the following values:

- `prod`: production environment. The constant `YII_ENV_PROD` will evaluate as true.
  This is the default value of `YII_ENV` if you do not define it.
- `dev`: development environment. The constant `YII_ENV_DEV` will evaluate as true.
- `test`: testing environment. The constant `YII_ENV_TEST` will evaluate as true.

With these environment constants, you may specify your configurations conditionally based on
the current environment. For example, your application configuration may contain the following
code to enable the [debug toolbar and debugger](tool-debugger.md) in development environment.

```php
$config = [...];

if (YII_ENV_DEV) {
    // configuration adjustments for 'dev' environment
    $config['bootstrap'][] = 'debug';
    $config['modules']['debug'] = 'yii\debug\Module';
}

return $config;
```