configuration.md 4.66 KB
Newer Older
1 2 3
Configuration
=============

4 5 6
Yii applications rely upon components to perform most of the common tasks, such as connecting to a database, routing browser
requests, and handling sessions. How these stock components behave can be adjusted by *configuring* your Yii application.
The majority of components have sensible defaults, so it's unlikely that you'll spend a lot of time configuring
Aris Karageorgos committed
7
them. Still there are some mandatory settings, such as the database connection, that you will have to establish.
8

9
How an application is configured depends on application template but there are some general principles applying in any case.
10 11 12 13 14 15 16 17 18

Configuring options in bootstrap file
-------------------------------------

For each application in Yii there is at least one bootstrap file. For web applications it's typically `index.php`, for
console applications it's `yii`. Both are doing nearly the same job:

1. Setting common constants.
2. Including Yii itself.
19
3. Including [Composer autoloader](http://getcomposer.org/doc/01-basic-usage.md#autoloading).
20 21 22
4. Reading config file into `$config`.
5. Creating new application instance using `$config` and running it.

23
The Bootstrap file is not the part of framework but your application so it's OK to adjust it to fit your application. Typical
24 25 26 27 28
adjustments are the value of `YII_DEBUG` that should never be `true` on production and the way config is read:

```php
defined('YII_DEBUG') or define('YII_DEBUG', false);
```
29 30 31 32 33

Configuring application instance
--------------------------------

It was mentioned above that application is configured in bootstrap file when its instance is created. Config is typically
34
stored in a PHP file in the `/config` directory of the application and looks like the following:
35 36 37

```php
<?php
Alexander Makarov committed
38
return [
39 40
	'id' => 'applicationId',
	'basePath' => dirname(__DIR__),
Alexander Makarov committed
41
	'components' => [
42
		// configuration of application components goes here...
Alexander Makarov committed
43
	],
44
	'params' => require(__DIR__ . '/params.php'),
marsuboss committed
45
];
46 47
```

48
In the above array keys are names of application properties. Depending on application type you can check properties of
49
either [[yii\web\Application]] or [[yii\console\Application]]. Both are extended from [[yii\base\Application]].
50 51 52 53

> Note that you can configure not only public class properties but anything accessible via setter. For example, to
  configure runtime path you can use key named `runtimePath`. There's no such property in the application class but
  since there's a corresponding setter named `setRuntimePath` it will be properly configured.
54
  This feature is added to any class that extends from [[yii\base\Object]] which is nearly any class of the Yii framework.
55 56 57 58 59 60 61 62

Configuring application components
----------------------------------

Majority of Yii functionality are application components. These are attached to application via its `components` property:

```php
<?php
Alexander Makarov committed
63
return [
64 65
	'id' => 'applicationId',
	'basePath' => dirname(__DIR__),
Alexander Makarov committed
66 67 68 69 70
	'components' => [
		'cache' => ['class' => 'yii\caching\FileCache'],
		'user' => ['identityClass' => 'app\models\User'],
		'errorHandler' => ['errorAction' => 'site/error'],
		'log' => [
71
			'traceLevel' => YII_DEBUG ? 3 : 0,
Alexander Makarov committed
72 73
			'targets' => [
				[
74
					'class' => 'yii\log\FileTarget',
Alexander Makarov committed
75 76 77 78 79
					'levels' => ['error', 'warning'],
				],
			],
		],
	],
80
	// ...
Alexander Makarov committed
81
];
82 83 84 85
```

In the above four components are configured: `cache`, `user`, `errorHandler`, `log`. Each entry key is a component ID
and the value is the configuration array. ID is used to access the component like `\Yii::$app->myComponent`.
86
Configuration array has one special key named `class` that sets the component class. The rest of the keys and values are used
87 88
to configure component properties in the same way as top-level keys are used to configure application properties.

89 90
Each application has a predefined set of components. In case of configuring one of these, the `class` key is omitted and
application default class is used instead. You can check `registerCoreComponents()` method of the application you are using
91 92 93 94 95 96 97 98
to get a list of component IDs and corresponding classes.

Note that Yii is smart enough to configure the component when it's actually used i.e. if `cache` is never used it will
not be instantiated and configured at all.

Setting component defaults classwide
------------------------------------

99 100 101 102 103 104 105 106 107 108 109 110 111 112 113
For each component you can specifiy classwide defaults. For example, if we want to change class for all `LinkPager`
widgets without specifying it over and over again when widget is called we can do it like the following:

```php
\Yii::$objectConfig = [
	'yii\widgets\LinkPager' => [
		'options' => [
			'class' => 'pagination',
		],
	],
];
```

The code above should be executed once before `LinkPager` widget is used. It can be done in `index.php`, application
config or anywhere else.