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

4 5
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.
Larry Ullman committed
6
The majority of components have sensible default settings, so it's unlikely that you'll do a lot of configuration. Still, there are some mandatory configuration settings that you will have to establish, such as the database connection.
7

Larry Ullman committed
8
How an application is configured depends upon the application template in use, but there are some general principles that apply in every Yii case.
9

Larry Ullman committed
10 11
Configuring options in the bootstrap file
-----------------------------------------
12

Larry Ullman committed
13 14
For each application in Yii there is at least one bootstrap file: a PHP script through which all requests are handled. For web applications, the bootstrap file is  typically `index.php`; for
console applications, the bootstrap file is `yii`. Both bootstrap files perform nearly the same job:
15 16

1. Setting common constants.
Larry Ullman committed
17
2. Including the Yii framework itself.
18
3. Including [Composer autoloader](http://getcomposer.org/doc/01-basic-usage.md#autoloading).
Larry Ullman committed
19 20
4. Reading the configuration file into `$config`.
5. Creating a new application instance, configured via `$config`, and running that instance.
21

Larry Ullman committed
22 23 24 25 26
Like any resource in your Yii application, the bootstrap file can be edited to fit your needs. A typical change is to the value of `YII_DEBUG`. This constant should be `true` during development, but always `false` on production sites.

The default bootstrap structure sets `YII_DEBUG` to `false` if not defined:

```php
27
defined('YII_DEBUG') or define('YII_DEBUG', false);
Larry Ullman committed
28 29 30
```

During development, you can change this to `true`:
31 32

```php
Larry Ullman committed
33
define('YII_DEBUG', true); // Development only 
34
defined('YII_DEBUG') or define('YII_DEBUG', false);
35
```
36

Larry Ullman committed
37 38
Configuring the application instance
------------------------------------
39

Larry Ullman committed
40 41
An application instance is configured when it's created in the bootstrap file. The configuration is typically
stored in a PHP file stored in the `/config` application directory. The file has this structure to begin:
42 43 44

```php
<?php
Alexander Makarov committed
45
return [
46 47
	'id' => 'applicationId',
	'basePath' => dirname(__DIR__),
Alexander Makarov committed
48
	'components' => [
49
		// configuration of application components goes here...
Alexander Makarov committed
50
	],
51
	'params' => require(__DIR__ . '/params.php'),
marsuboss committed
52
];
53 54
```

Larry Ullman committed
55 56
The configuration is a large array of key-value pairs. In the above, the array keys are the names of application properties. Depending upon the application type, you can configure the properties of
either [[yii\web\Application]] or [[yii\console\Application]] classes. Both classes extend  [[yii\base\Application]].
57

Larry Ullman committed
58 59 60 61
Note that you can configure not only public class properties, but any property accessible via a setter. For example, to
  configure the runtime path, you can use a key named `runtimePath`. There's no such property in the application class, but
  since the class has a corresponding setter named `setRuntimePath`, `runtimePath` becomes configurable.
  The ability to configure properties via setters is available to any class that extends from [[yii\base\Object]], which is nearly every class in the Yii framework.
62 63 64 65

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

Larry Ullman committed
66
The majority of the Yii functionality comes from application components. These components are attached to the application instance via the instance's `components` property:
67 68 69

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

Larry Ullman committed
91 92 93 94
In the above code, four components are configured: `cache`, `user`, `errorHandler`, `log`. Each entry's key is a component ID. The values are subarrays used to configure that component. The component ID is also used to access the component anywhere within the application, using code like `\Yii::$app->myComponent`.

The configuration array has one special key named `class` that identifies the component's base class. The rest of the keys and values are used
to configure component properties in the same way as top-level keys are used to configure the application's properties.
95

Larry Ullman committed
96
Each application has a predefined set of components. To configure one of these, the `class` key can be omitted to use the default Yii class for that component. You can check the `registerCoreComponents()` method of the application you are using
97 98
to get a list of component IDs and corresponding classes.

Larry Ullman committed
99
Note that Yii is smart enough to only configure the component when it's actually being used: for example, if you configure the `cache` component in your configuration file but never use the `cache` component in your code, no instance of that component will be created and no time is wasted configuring it.
100 101 102 103

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

Larry Ullman committed
104 105
For each component you can specifiy classwide defaults. For example, if you want to change the class used for all `LinkPager`
widgets without specifying the class for every widget usage, you can do the following:
106 107 108 109 110 111 112 113 114 115 116

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

Larry Ullman committed
117 118
The code above should be executed once before `LinkPager` widget is used. It can be done in `index.php`, the application
configuration file, or anywhere else.