structure-applications.md 25.8 KB
Newer Older
Qiang Xue committed
1 2 3
Applications
============

Qiang Xue committed
4 5 6
Applications are objects that govern the overall structure and lifecycle of Yii application systems.
Each Yii application system contains a single application object which is created in
the [entry script](structure-entry-scripts.md) and is globally accessible through the expression `\Yii::$app`.
Qiang Xue committed
7

Qiang Xue committed
8 9 10 11
> Info: Depending on the context, when we say "an application", it can mean either an application
  object or an application system.

There are two types of applications: [[yii\web\Application|Web applications]] and
Qiang Xue committed
12 13 14 15
[[yii\console\Application|console applications]]. As the names indicate, the former mainly handles
Web requests while the latter console command requests.


Qiang Xue committed
16
## Application Configurations <a name="application-configurations"></a>
Qiang Xue committed
17

Qiang Xue committed
18 19
When an [entry script](structure-entry-scripts.md) creates an application, it will load
a [configuration](concept-configurations.md) and apply it to the application, like the following:
Qiang Xue committed
20 21 22 23 24 25 26 27 28 29 30 31

```php
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();
```

Qiang Xue committed
32 33 34 35 36 37
Like normal [configurations](concept-configurations.md), application configurations specify how
to initialize properties of application objects. Because application configurations are often
very complex, they usually are kept in [configuration files](concept-configurations.md#configuration-files),
like the `web.php` file in the above example.


Qiang Xue committed
38
## Application Properties <a name="application-properties"></a>
Qiang Xue committed
39 40 41 42 43 44 45

There are many important application properties that you should configure in application configurations.
These properties typically describe the environment that applications are running in.
For example, applications need to know how to load [controllers](structure-controllers.md),
where to store temporary files, etc. In the following, we will summarize these properties.


Qiang Xue committed
46
### Required Properties <a name="required-properties"></a>
Qiang Xue committed
47 48 49 50

In any application, you should at least configure two properties: [[yii\base\Application::id|id]]
and [[yii\base\Application::basePath|basePath]].

Qiang Xue committed
51

Qiang Xue committed
52
#### [[yii\base\Application::id|id]] <a name="id"></a>
Qiang Xue committed
53

Qiang Xue committed
54 55 56 57
The [[yii\base\Application::id|id]] property specifies a unique ID that differentiates an application
from others. It is mainly used programmatically. Although not a requirement, for best interoperability
it is recommended that you use alphanumeric characters only when specifying an application ID.

Qiang Xue committed
58

Qiang Xue committed
59
#### [[yii\base\Application::basePath|basePath]] <a name="basePath"></a>
Qiang Xue committed
60

Qiang Xue committed
61 62 63 64 65 66 67 68 69 70 71 72 73 74
The [[yii\base\Application::basePath|basePath]] property specifies the root directory of an application.
It is the directory that contains all protected source code of an application 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 configure the [[yii\base\Application::basePath|basePath]] property using a directory path
or a [path alias](concept-aliases.md). In both forms, the corresponding directory must exist, or an exception
will be thrown. The path will be normalized by calling the `realpath()` function.

The [[yii\base\Application::basePath|basePath]] property is often used to derive other important
paths (e.g. the runtime path). For this reason, a path alias named `@app` is predefined to represent this
path. Derived paths may then be formed using this alias (e.g. `@app/runtime` to refer to the runtime directory).


Qiang Xue committed
75
### Important Properties <a name="important-properties"></a>
Qiang Xue committed
76

Qiang Xue committed
77 78
The properties described in this subsection often need to be configured because they differ across
different applications.
Qiang Xue committed
79 80


Qiang Xue committed
81
#### [[yii\base\Application::aliases|aliases]] <a name="aliases"></a>
Qiang Xue committed
82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99

This property allows you to define a set of [aliases](concept-aliases.md) in terms of an array.
The array keys are alias names, and the array values are the corresponding path definitions.
For example,

```php
[
    'aliases' => [
        '@name1' => 'path/to/path1',
        '@name2' => 'path/to/path2',
    ],
]
```

This property is provided such that you can define aliases in terms of application configurations instead of
the method calls [[Yii::setAlias()]].


Qiang Xue committed
100
#### [[yii\base\Application::bootstrap|bootstrap]] <a name="bootstrap"></a>
Qiang Xue committed
101 102 103 104 105 106 107 108 109 110 111 112

This is a very useful property. It allows you to specify an array of components that should
be run during the application [[yii\base\Application::bootstrap()|bootstrapping process]].
For example, if you want a [module](structure-modules.md) to customize the [URL rules](runtime-url-handling.md),
you may list its ID as an element in this property.

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

- an application component ID as specified via [components](#components).
- a module ID as specified via [modules](#modules).
- a class name.
- a configuration array.
Qiang Xue committed
113
- an anonymous function that creates and returns a component.
Qiang Xue committed
114 115 116 117 118 119 120 121 122 123

For example,

```php
[
    'bootstrap' => [
        // an application component ID or module ID
        'demo',

        // a class name
Qiang Xue committed
124
        'app\components\Profiler',
Qiang Xue committed
125 126 127 128 129

        // a configuration array
        [
            'class' => 'app\components\Profiler',
            'level' => 3,
Qiang Xue committed
130 131 132 133
        ],

        // an anonymous function
        function () {
134
            return new app\components\Profiler();
Qiang Xue committed
135
        }
Qiang Xue committed
136 137 138 139
    ],
]
```

Qiang Xue committed
140 141 142 143 144 145
> 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 () {
146
        return Yii::$app->getModule('user');
Qiang Xue committed
147 148 149 150 151
    },
]
```


Qiang Xue committed
152 153
During the bootstrapping process, each component will be instantiated. If the component class
implements [[yii\base\BootstrapInterface]], its [[yii\base\BootstrapInterface::bootstrap()|bootstrap()]] method
Carsten Brandt committed
154
will also be called.
Qiang Xue committed
155

Qiang Xue committed
156
Another practical example is in the application configuration for the [Basic Application Template](start-installation.md),
Qiang Xue committed
157
where the `debug` and `gii` modules are configured as bootstrapping components when the application is running
Qiang Xue committed
158 159 160 161 162 163 164 165 166 167 168 169 170 171
in development environment,

```php
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
Qiang Xue committed
172
  for each request, the same set of components need to be run. So use bootstrapping components judiciously.
Qiang Xue committed
173

Qiang Xue committed
174

Qiang Xue committed
175
#### [[yii\web\Application::catchAll|catchAll]] <a name="catchAll"></a>
Qiang Xue committed
176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194

This property is supported by [[yii\web\Application|Web applications]] only. It specifies
a [controller action](structure-controllers.md) 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 configuration is an array whose first element specifies 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,

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


Qiang Xue committed
195
#### [[yii\base\Application::components|components]] <a name="components"></a>
Qiang Xue committed
196

Qiang Xue committed
197
This is the single most important property. It allows you to register a list of named components
198
called [application components](structure-application-components.md) that you can use in other places. For example,
Qiang Xue committed
199 200 201 202 203 204 205 206 207 208 209 210 211 212 213

```php
[
    'components' => [
        'cache' => [
            'class' => 'yii\caching\FileCache',
        ],
        'user' => [
            'identityClass' => 'app\models\User',
            'enableAutoLogin' => true,
        ],
    ],
]
```

214
Each application component is specified as a key-value pair in the array. The key represents the component ID,
Qiang Xue committed
215 216 217 218 219
while the value represents the component class name or [configuration](concept-configurations.md).

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

220
Please read the [Application Components](structure-application-components.md) section for details.
Qiang Xue committed
221 222


Qiang Xue committed
223
#### [[yii\base\Application::controllerMap|controllerMap]] <a name="controllerMap"></a>
Qiang Xue committed
224

Qiang Xue committed
225 226 227 228 229 230 231 232 233 234 235 236 237
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](#controllerNamespace) (e.g. the ID `post` would be mapped
to `app\controllers\PostController`). By configuring this property, you can break the convention for
specific controllers. In the following example, `account` will be mapped to
`app\controllers\UserController`, while `article` will be mapped to `app\controllers\PostController`.

```php
[
    'controllerMap' => [
        [
            'account' => 'app\controllers\UserController',
            'article' => [
                'class' => 'app\controllers\PostController',
Qiang Xue committed
238
                'enableCsrfValidation' => false,
Qiang Xue committed
239 240 241 242 243 244 245 246 247 248
            ],
        ],
    ],
]
```

The array keys of this property represent the controller IDs, while the array values represent the corresponding
controller class names or [configurations](concept-configurations.md).


Qiang Xue committed
249
#### [[yii\base\Application::controllerNamespace|controllerNamespace]] <a name="controllerNamespace"></a>
Qiang Xue committed
250

Qiang Xue committed
251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266
This property specifies the default namespace under which controller classes should be located. It defaults to
`app\controllers`. If a controller ID is `post`, by convention the corresponding controller class name (without
namespace) would be `PostController`, and the fully qualified class name would be `app\controllers\PostController`.

Controller classes may also be located under sub-directories of the directory corresponding to this namespace.
For example, given a controller ID `admin/post`, the corresponding fully qualified controller class would
be `app\controllers\admin\PostController`.

It is important that the fully qualified controller classes should be [autoloadable](concept-autoloading.md)
and the actual namespace of your controller classes match the value of this property. Otherwise,
you will receive "Page Not Found" error when accessing the application.

In case you want to break the convention as described above, you may configure the [controllerMap](#controllerMap)
property.


Qiang Xue committed
267
#### [[yii\base\Application::language|language]] <a name="language"></a>
Qiang Xue committed
268

Qiang Xue committed
269
This property specifies the language in which the application should display content to end users.
270 271
The default value of this property is `en`, meaning English. You should configure this property
if your application needs to support multiple languages.
Qiang Xue committed
272 273 274 275

The value of this property determines various [internationalization](tutorial-i18n.md) aspects,
including message translation, date formatting, number formatting, etc. For example, the [[yii\jui\DatePicker]] widget
will use this property value by default to determine in which language the calendar should be displayed and how
276
should the date be formatted.
Qiang Xue committed
277 278 279 280 281 282 283

It is recommended that you specify a language in terms of an [IETF language tag](http://en.wikipedia.org/wiki/IETF_language_tag).
For example, `en` stands for English, while `en-US` stands for English (United States).

More details about this property can be found in the [Internationalization](tutorial-i18n.md) section.


Qiang Xue committed
284
#### [[yii\base\Application::modules|modules]] <a name="modules"></a>
Qiang Xue committed
285

Qiang Xue committed
286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308
This property specifies the [modules](structure-modules.md) that the application contains.

The property takes an array of module classes or [configurations](concept-configurations.md) with the array keys
being the module IDs. For example,

```php
[
    'modules' => [
        // a "booking" module specified with the module class
        'booking' => 'app\modules\booking\BookingModule',

        // a "comment" module specified with a configuration array
        'comment' => [
            'class' => 'app\modules\comment\CommentModule',
            'db' => 'db',
        ],
    ],
]
```

Please refer to the [Modules](structure-modules.md) section for more details.


Qiang Xue committed
309
#### [[yii\base\Application::name|name]] <a name="name"></a>
Qiang Xue committed
310

Qiang Xue committed
311 312 313 314 315 316 317
This property specifies the application name that may be displayed to end users. Unlike the
[[yii\base\Application::id|id]] property which should take a unique value, the value of this property is mainly for
display purpose and does not need to be unique.

You do not always need to configure this property if none of your code is using it.


Qiang Xue committed
318
#### [[yii\base\Application::params|params]] <a name="params"></a>
Qiang Xue committed
319

Qiang Xue committed
320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343
This property specifies an array of globally accessible application parameters. Instead of using hardcoded
numbers and strings everywhere in your code, it is a good practice to define them as application parameters
in a single place and use the parameters in places where needed. For example, you may define the thumbnail
image size as a parameter like the following:

```php
[
    'params' => [
        'thumbnail.size' => [128, 128],
    ],
]
```

Then in your code where you need to use the size value, you can simply use the code like the following:

```php
$size = \Yii::$app->params['thumbnail.size'];
$width = \Yii::$app->params['thumbnail.size'][0];
```

Later if you decide to change the thumbnail size, you only need to modify it in the application configuration
without touching any dependent code.


Qiang Xue committed
344
#### [[yii\base\Application::sourceLanguage|sourceLanguage]] <a name="sourceLanguage"></a>
345

346 347
This property specifies the language that the application code is written in. The default value is `'en-US'`,
meaning English (United States). You should configure this property if the text content in your code is not in English.
348 349 350 351 352 353 354 355

Like the [language](#language) property, you should configure this property in terms of
an [IETF language tag](http://en.wikipedia.org/wiki/IETF_language_tag). For example, `en` stands for English,
while `en-US` stands for English (United States).

More details about this property can be found in the [Internationalization](tutorial-i18n.md) section.


Qiang Xue committed
356
#### [[yii\base\Application::timeZone|timeZone]] <a name="timeZone"></a>
Qiang Xue committed
357 358

This property is provided as an alternative way of setting the default time zone of PHP runtime.
359 360
By configuring this property, you are essentially calling the PHP function
[date_default_timezone_set()](http://php.net/manual/en/function.date-default-timezone-set.php). For example,
Qiang Xue committed
361 362 363 364 365 366 367 368

```php
[
    'timeZone' => 'America/Los_Angeles',
]
```


Qiang Xue committed
369
#### [[yii\base\Application::version|version]] <a name="version"></a>
Qiang Xue committed
370

Qiang Xue committed
371 372 373
This property specifies the version of the application. It defaults to `'1.0'`. You do not always need to configure
this property if none of your code is using it.

Qiang Xue committed
374

Qiang Xue committed
375
### Useful Properties <a name="useful-properties"></a>
Qiang Xue committed
376

Qiang Xue committed
377 378
The properties described in this subsection are not commonly configured because their default values
stipulate common conventions. However, you may still configure them in case you want to break the conventions.
Qiang Xue committed
379 380


Qiang Xue committed
381
#### [[yii\base\Application::charset|charset]] <a name="charset"></a>
Qiang Xue committed
382

Qiang Xue committed
383 384 385 386
This property specifies the charset that the application uses. The default value is `'UTF-8'` which should
be kept as is for most applications unless you are working with some legacy systems that use a lot of non-unicode data.


Qiang Xue committed
387
#### [[yii\base\Application::defaultRoute|defaultRoute]] <a name="defaultRoute"></a>
Qiang Xue committed
388 389 390 391 392 393

This property specifies the [route](runtime-routing.md) that an application should use when a request
does not specify one. The route may consist of child module ID, controller ID, and/or action ID.
For example, `help`, `post/create`, `admin/post/create`. If action ID is not given, it will take the default
value as specified in [[yii\base\Controller::defaultAction]].

Bazilio committed
394
For [[yii\web\Application|Web applications]], the default value of this property is `'site'`, which means
Qiang Xue committed
395 396 397
the `SiteController` controller and its default action should be used. As a result, if you access
the application without specifying a route, it will show the result of `app\controllers\SiteController::actionIndex()`.

Bazilio committed
398
For [[yii\console\Application|console applications]], the default value is `'help'`, which means the core command
Qiang Xue committed
399 400 401 402
[[yii\console\controllers\HelpController::actionIndex()]] should be used. As a result, if you run the command `yii`
without providing any arguments, it will display the help information.


Qiang Xue committed
403
#### [[yii\base\Application::extensions|extensions]] <a name="extensions"></a>
Qiang Xue committed
404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432

This property specifies the list of [extensions](structure-extensions.md) that are installed and used by the application.
By default, it will take the array returned by the file `@vendor/yiisoft/extensions.php`. The `extensions.php` file
is generated and maintained automatically when you use [Composer](http://getcomposer.org) to install extensions.
So in most cases, you do not need to configure this property.

In the special case when you want to maintain extensions manually, you may configure this property like the following:

```php
[
    'extensions' => [
        [
            'name' => 'extension name',
            'version' => 'version number',
            'bootstrap' => 'BootstrapClassName',  // optional, may also be a configuration array
            'alias' => [  // optional
                '@alias1' => 'to/path1',
                '@alias2' => 'to/path2',
            ],
        ],

        // ... more extensions like the above ...

    ],
]
```

As you can see, the property takes an array of extension specifications. Each extension is specified with an array
consisting of `name` and `version` elements. If an extension needs to run during the [bootstrap](runtime-bootstrapping.md)
Qiang Xue committed
433
process, a `bootstrap` element may be specified with a bootstrapping class name or a [configuration](concept-configurations.md)
Qiang Xue committed
434
array. An extension may also define a few [aliases](concept-aliases.md).
Qiang Xue committed
435 436


Qiang Xue committed
437
#### [[yii\base\Application::layout|layout]] <a name="layout"></a>
Qiang Xue committed
438

439 440 441 442 443 444
This property specifies the name of the default layout that should be used when rendering a [view](structure-views.md).
The default value is `'main'`, meaning the layout file `main.php` under the [layout path](#layoutPath) should be used.
If both of the [layout path](#layoutPath) and the [view path](#viewPath) are taking the default values,
the default layout file can be represented as the path alias `@app/views/layouts/main.php`.

You may configure this property to be `false` if you want to disable layout by default, although this is very rare.
Qiang Xue committed
445

Qiang Xue committed
446

Qiang Xue committed
447
#### [[yii\base\Application::layoutPath|layoutPath]] <a name="layoutPath"></a>
Qiang Xue committed
448

449 450 451 452 453 454 455
This property specifies the path where layout files should be looked for. The default value is
the `layouts` sub-directory under the [view path](#viewPath). If the [view path](#viewPath) is taking
its default value, the default layout path can be represented as the path alias `@app/views/layouts`.

You may configure it as a directory or a path [alias](concept-aliases.md).


Qiang Xue committed
456
#### [[yii\base\Application::runtimePath|runtimePath]] <a name="runtimePath"></a>
Qiang Xue committed
457

458 459 460 461 462 463 464 465 466
This property specifies the path where temporary files, such as log files, cache files, can be generated.
The default value is the directory represented by the alias `@app/runtime`.

You may configure it as a directory or a path [alias](concept-aliases.md). Note that the runtime path must
be writable by the process running the application. And the path should be protected from being accessed
by end users because the temporary files under it may contain sensitive information.

To simplify accessing to this path, Yii has predefined a path alias named `@runtime` for it.

Qiang Xue committed
467

Qiang Xue committed
468
#### [[yii\base\Application::viewPath|viewPath]] <a name="viewPath"></a>
Qiang Xue committed
469

470 471 472 473
This property specifies the root directory where view files are located. The default value is the directory
represented by the alias `@app/views`. You may configure it as a directory or a path [alias](concept-aliases.md).


Qiang Xue committed
474
#### [[yii\base\Application::vendorPath|vendorPath]] <a name="vendorPath"></a>
Qiang Xue committed
475

476 477 478 479 480 481 482 483 484 485
This property specifies the vendor directory managed by [Composer](http://getcomposer.org). It contains
all third party libraries used by your application, including the Yii framework. The default value is
the directory represented by the alias `@app/vendor`.

You may configure this property as a directory or a path [alias](concept-aliases.md). When you modify
this property, make sure you also adjust the Composer configuration accordingly.

To simplify accessing to this path, Yii has predefined a path alias named `@vendor` for it.


Qiang Xue committed
486
#### [[yii\console\Application::enableCoreCommands|enableCoreCommands]] <a name="enableCoreCommands"></a>
Qiang Xue committed
487

488 489
This property is supported by [[yii\console\Application|console applications]] only. It specifies
whether the core commands included in the Yii release should be enabled. The default value is `true`.
Qiang Xue committed
490 491


Qiang Xue committed
492
## Application Events <a name="application-events"></a>
Qiang Xue committed
493

494 495
An application triggers several events during the lifecycle of handling an request. You may attach event
handlers to these events in application configurations like the following,
Qiang Xue committed
496

497 498 499 500 501 502 503 504 505 506
```php
[
    'on beforeRequest' => function ($event) {
        // ...
    },
]
```

The use of the `on eventName` syntax is described in the [Configurations](concept-configurations.md#configuration-format)
section.
Qiang Xue committed
507

508 509
Alternatively, you may attach event handlers during the [bootstrapping process](runtime-bootstrapping.md) process
after the application instance is created. For example,
Qiang Xue committed
510

511 512 513 514 515
```php
\Yii::$app->on(\yii\base\Application::EVENT_BEFORE_REQUEST, function ($event) {
    // ...
});
```
Qiang Xue committed
516

Qiang Xue committed
517
### [[yii\base\Application::EVENT_BEFORE_REQUEST|EVENT_BEFORE_REQUEST]] <a name="beforeRequest"></a>
Qiang Xue committed
518

519
This event is triggered *before* an application handles a request. The actual event name is `beforeRequest`.
Qiang Xue committed
520

521 522 523
When this event is triggered, the application instance has been configured and initialized. So it is a good place
to insert your custom code via the event mechanism to intercept the request handling process. For example,
in the event handler, you may dynamically set the [[yii\base\Application::language]] property based on some parameters.
Qiang Xue committed
524 525


526
### [[yii\base\Application::EVENT_AFTER_REQUEST|EVENT_AFTER_REQUEST]] <a name="afterRequest"></a>
Qiang Xue committed
527

528 529
This event is triggered *after* an application finishes handling a request but *before* sending the response.
The actual event name is `afterRequest`.
Qiang Xue committed
530

531 532
When this event is triggered, the request handling is completed and you may take this chance to do some postprocessing
of the request or customize the response.
Qiang Xue committed
533

534 535
Note that the [[yii\web\Response|response]] component also triggers some events while it is sending out
response content to end users. Those events are triggered *after* this event.
Qiang Xue committed
536 537


538
### [[yii\base\Application::EVENT_BEFORE_ACTION|EVENT_BEFORE_ACTION]] <a name="beforeAction"></a>
Qiang Xue committed
539

540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556
This event is triggered *before* running every [controller action](structure-controllers.md).
The actual event name is `beforeAction`.

The event parameter is an instance of [[yii\base\ActionEvent]]. An event handler may set
the [[yii\base\ActionEvent::isValid]] property to be `false` to stop running the action.
For example,

```php
[
    'on beforeAction' => function ($event) {
        if (some condition) {
            $event->isValid = false;
        } else {
        }
    },
]
```
Qiang Xue committed
557

558
Note that the same `beforeAction` event is also triggered by [modules](structure-modules.md)
Bazilio committed
559
and [controllers](structure-controllers.md). Application objects are the first ones
560 561
triggering this event, followed by modules (if any), and finally controllers. If an event handler
sets [[yii\base\ActionEvent::isValid]] to be `false`, all the following events will NOT be triggered.
Qiang Xue committed
562 563


564
### [[yii\base\Application::EVENT_AFTER_ACTION|EVENT_AFTER_ACTION]] <a name="afterAction"></a>
Qiang Xue committed
565

566 567
This event is triggered *after* running every [controller action](structure-controllers.md).
The actual event name is `afterAction`.
Qiang Xue committed
568

569 570 571
The event parameter is an instance of [[yii\base\ActionEvent]]. Through
the [[yii\base\ActionEvent::result]] property, an event handler may access or modify the action result.
For example,
Qiang Xue committed
572

573 574 575 576 577 578 579 580 581 582
```php
[
    'on afterAction' => function ($event) {
        if (some condition) {
            // modify $event->result
        } else {
        }
    },
]
```
Qiang Xue committed
583

584
Note that the same `afterAction` event is also triggered by [modules](structure-modules.md)
Bazilio committed
585
and [controllers](structure-controllers.md). These objects trigger this event in the reverse order
586 587
as for that of `beforeAction`. That is, controllers are the first objects triggering this event,
followed by modules (if any), and finally applications.
Qiang Xue committed
588 589


Qiang Xue committed
590
## Application Lifecycle <a name="application-lifecycle"></a>
Qiang Xue committed
591

592 593
When an [entry script](structure-entry-scripts.md) is being executed to handle a request,
an application will undergo the following lifecycle:
Qiang Xue committed
594

595 596
1. The entry script loads the application configuration as an array.
2. The entry script creates a new instance of the application:
Qiang Xue committed
597 598 599 600 601
  * [[yii\base\Application::preInit()|preInit()]] is called, which configures some high priority
    application properties, such as [[yii\base\Application::basePath|basePath]].
  * Register the [[yii\base\Application::errorHandler|error handler]].
  * Configure application properties.
  * [[yii\base\Application::init()|init()]] is called which further calls
Qiang Xue committed
602
    [[yii\base\Application::bootstrap()|bootstrap()]] to run bootstrapping components.
603
3. The entry script calls [[yii\base\Application::run()]] to run the application:
Qiang Xue committed
604 605 606 607 608
  * Trigger the [[yii\base\Application::EVENT_BEFORE_REQUEST|EVENT_BEFORE_REQUEST]] event.
  * Handle the request: resolve the request into a [route](runtime-routing.md) and the associated parameters;
    create the module, controller and action objects as specified by the route; and run the action.
  * Trigger the [[yii\base\Application::EVENT_AFTER_REQUEST|EVENT_AFTER_REQUEST]] event.
  * Send response to the end user.
609
4. The entry script receives the exit status from the application and completes the request processing.