configuration.md

Configuration

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 them. Still there are some mandatory settings, such as the database connection, that you will have to establish.

How an application is configured depends on application template but there are some general principles applying in any case.

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.
3. Including Composer autoloader.
4. Reading config file into $config.
5. Creating new application instance using $config and running it.

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

defined('YII_DEBUG') or define('YII_DEBUG', false);

Configuring application instance

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

<?php
return [
	'id' => 'applicationId',
	'basePath' => dirname(__DIR__),
	'components' => [
		// configuration of application components goes here...
	],
	'params' => require(__DIR__ . '/params.php'),
];

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

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. This feature is added to any class that extends from [[yii\base\Object]] which is nearly any class of the Yii framework.

Configuring application components

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

<?php
return [
	'id' => 'applicationId',
	'basePath' => dirname(__DIR__),
	'components' => [
		'cache' => ['class' => 'yii\caching\FileCache'],
		'user' => ['identityClass' => 'app\models\User'],
		'errorHandler' => ['errorAction' => 'site/error'],
		'log' => [
			'traceLevel' => YII_DEBUG ? 3 : 0,
			'targets' => [
				[
					'class' => 'yii\log\FileTarget',
					'levels' => ['error', 'warning'],
				],
			],
		],
	],
	// ...
];

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. Configuration array has one special key named class that sets the component 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 application properties.

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 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

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:

\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.