APPLICATIONS 51 1 Application Congurations

When an entry script creates an application, it will load a conguration and apply it to the application, like the following:

require(__DIR__ . '/../vendor/autoload.php');

require(__DIR__ . '/../vendor/yiisoft/yii2/Yii.php');

// load application configuration

$config = require(__DIR__ . '/../config/web.php');

// instantiate and configure the application (new yii\web\Application($config))->run();

Like normal congurations, application congurations specify how to ini-tialize properties of application objects. Because application congurations are often very complex, they usually are kept in conguration les, like the

web.php le in the above example.

3.3.2 Application Properties

There are many important application properties that you should congure in application congurations. These properties typically describe the envi-ronment that applications are running in. For example, applications need to know how to load controllers, where to store temporary les, etc. In the following, we will summarize these properties.

Required Properties

In any application, you should at least congure two properties: id and basePath.

id The id property species a unique ID that dierentiates an application from others. It is mainly used programmatically. Although not a require-ment, for best interoperability it is recommended that you use alphanumeric characters only when specifying an application ID.

basePath The basePath property species the root directory of an appli-cation. It is the directory that contains all protected source code of an ap-plication system. Under this directory, you normally will see sub-directories such as models, views, controllers, which contain source code corresponding to the MVC pattern.

You may congure the basePath property using a directory path or a path alias. In both forms, the corresponding directory must exist, or an exception will be thrown. The path will be normalized by calling therealpath ()function.

52 CHAPTER 3. APPLICATION STRUCTURE The basePath property is often used to derive other important paths (e.g.

the runtime path). For this reason, a path alias named^@appis predened to represent this path. Derived paths may then be formed using this alias (e.g.

@app/runtimeto refer to the runtime directory).

Important Properties

The properties described in this subsection often need to be congured be-cause they dier across dierent applications.

aliases This property allows you to dene a set of aliases in terms of an array. The array keys are alias names, and the array values are the corresponding path denitions. For example,

[

'aliases' => [

'@name1' => 'path/to/path1', '@name2' => 'path/to/path2', ] ],

This property is provided such that you can dene aliases in terms of appli-cation congurations instead of the method calls Yii::setAlias().

bootstrap This is a very useful property. It allows you to specify an array of components that should be run during the application bootstrapping process. For example, if you want a module to customize the URL rules, you may list its ID as an element in this property.

Each component listed in this property may be specied in one of the following formats:

• an application component ID as specied via components.

• a module ID as specied via modules.

• a class name.

• a conguration array.

• an anonymous function that creates and returns a component.

For example,

[

'bootstrap' => [

// an application component ID or module ID 'demo',

// a class name

'app\components\Profiler', // a configuration array [

'class' => 'app\components\Profiler', 'level' => 3,

3.3. APPLICATIONS 53

],

// an anonymous function function () {

return new app\components\Profiler();

} ] ],

Info: If a module ID is the same as an application component ID, the application component will be used during the bootstrapping process. If you want to use the module instead, you may specify it using an anonymous function like the following: `php [

function () {

return Yii::$app->getModule('user');

},

]`

During the bootstrapping process, each component will be instantiated. If the component class implements yii\base\BootstrapInterface, its bootstrap() method will also be called.

Another practical example is in the application conguration for the Ba-sic Project Template, where the debug and gii modules are congured as bootstrapping components when the application is running in development environment,

if (YII_ENV_DEV) {

// configuration adjustments for 'dev' environment

$config['bootstrap'][] = 'debug';

$config['modules']['debug'] = 'yii\debug\Module';

$config['bootstrap'][] = 'gii';

$config['modules']['gii'] = 'yii\gii\Module';

}

Note: Putting too many components in bootstrap will degrade the performance of your application because for each request, the same set of components need to be run. So use bootstrapping components judiciously.

catchAll This property is supported by Web applications only. It spec-ies a controller action which should handle all user requests. This is mainly used when the application is in maintenance mode and needs to handle all incoming requests via a single action.

The conguration is an array whose rst element species the route of the action. The rest of the array elements (key-value pairs) specify the parameters to be bound to the action. For example,

54 CHAPTER 3. APPLICATION STRUCTURE

[

'catchAll' => [ 'offline/notice', 'param1' => 'value1', 'param2' => 'value2', ],

]

components This is the single most important property. It allows you to register a list of named components called application components that you can use in other places. For example,

[ 'components' => [ 'cache' => [

'class' => 'yii\caching\FileCache', ],'user' => [

'identityClass' => 'app\models\User', 'enableAutoLogin' => true,

], ] ],

Each application component is specied as a key-value pair in the array. The key represents the component ID, while the value represents the component class name or conguration.

You can register any component with an application, and the component can later be accessed globally using the expression\Yii::$app->ComponentID.

Please read the Application Components section for details.

controllerMap This property allows you to map a controller ID to an arbitrary controller class. By default, Yii maps controller IDs to controller classes based on a convention (e.g. the ID ^post would be mapped to ^app\

controllers\PostController). By conguring this property, you can break the convention for specic controllers. In the following example,account will be mapped to app\controllers\UserController, while ^article will be mapped to

app\controllers\PostController.

[ 'controllerMap' => [

[ 'account' => 'app\controllers\UserController', 'article' => [

'class' => 'app\controllers\PostController', 'enableCsrfValidation' => false,

], ], ] ],

3.3. APPLICATIONS 55