Skip to content

Y
yii2
Commit d1ab9f72 by Qiang Xue
Options

Finished application guide [skip ci]

parent e4ff31cc
Showing with 210 additions and 75 deletions
docs/guide/concept-aliases.md
......@@ -109,7 +109,7 @@ The following is the list of the predefined aliases:
- `@yii`: the directory where the `BaseYii.php` file is located (also called the framework directory).
- `@app`: the [[yii\base\Application::basePath|base path]] of the currently running application.
- `@runtime`: the [[yii\base\Application::runtimePath|runtime path]] of the currently running application.
- `@vendor`: the Composer vendor directory.
- `@vendor`: the [[yii\base\Application::vendorPath|Composer vendor directory].
- `@webroot`: the Web root directory of the currently running Web application.
- `@web`: the base URL of the currently running Web application.
......
docs/guide/structure-applications.md
......@@ -249,12 +249,13 @@ property.
#### [[yii\base\Application::language|language]]
This property specifies the language in which the application should display content to end users.
You should configure this property if your application needs to support multiple languages.
The default value of this property is `en`, meaning English. You should configure this property
if your application needs to support multiple languages.
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
should the date be formatted. The default value of this property is `en`.
should the date be formatted.
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).
......@@ -322,11 +323,23 @@ Later if you decide to change the thumbnail size, you only need to modify it in
without touching any dependent code.
#### [[yii\base\Application::sourceLanguage|sourceLanguage]]
This property specifies the language that the application code is written in. The default value is `'en'`,
meaning English. You should configure this property if the text content in your code is not in English.
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.
#### [[yii\base\Application::timeZone|timeZone]]
This property is provided as an alternative way of setting the default time zone of PHP runtime.
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,
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,
```php
[
......@@ -405,120 +418,242 @@ array. An extension may also define a few [aliases](concept-aliases.md).
#### [[yii\base\Application::layout|layout]]
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.
#### [[yii\base\Application::layoutPath|layoutPath]]
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).
#### [[yii\base\Application::runtimePath|runtimePath]]
#### [[yii\base\Application::sourceLanguage|sourceLanguage]]
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.
#### [[yii\base\Application::viewPath|viewPath]]
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).
#### [[yii\base\Application::vendorPath|vendorPath]]
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.
#### [[yii\console\Application::enableCoreCommands|enableCoreCommands]]
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`.
## Application Components
Applications are [service locators](concept-service-locators.md). They host a set of the so-called
*application components* that provide different services for request processing. For example,
the `urlManager` component is responsible for routing Web requests to appropriate controllers;
the `db` component provides DB-related services; and so on.
## Application Events
Each application component has an ID that uniquely identifies itself among other application components
in the same application. You can access an application component through the expression `$app->ID`,
where `$app` refers to an application instance, and `ID` stands for the ID of an application component.
For example, you can use `Yii::$app->db` to get the [[yii\db\Connection|DB connection]], and `Yii::$app->cache`
to get the [[yii\caching\Cache|primary cache]] registered with the application.
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,
Application components can be any objects. You can register them with an application to make them
globally accessible. This is usually done by configuring the [[yii\base\Application::components]] property,
as described in the [components](#components) subsection.
```php
[
'on beforeRequest' => function ($event) {
// ...
},
]
```
The use of the `on eventName` syntax is described in the [Configurations](concept-configurations.md#configuration-format)
section.
Yii predefines a set of core application components to provide features common among different applications.
For example, the [[yii\web\Application::request|request]] component is used to collect information about
a user request and resolve it into a [route](runtime-routing.md). By configuring the properties of these core
components, you can customize nearly every aspect of Yii.
Alternatively, you may attach event handlers during the [bootstrapping process](runtime-bootstrapping.md) process
after the application instance is created. For example,
Below is the list of the predefined core application components:
```php
\Yii::$app->on(\yii\base\Application::EVENT_BEFORE_REQUEST, function ($event) {
// ...
});
```
- [assetManager|CWebApplication::assetManager]: [CAssetManager] -
manages the publishing of private asset files.
### [[yii\base\Application::EVENT_BEFORE_REQUEST|EVENT_BEFORE_REQUEST]]
- [authManager|CWebApplication::authManager]: [CAuthManager] - manages role-based access control (RBAC).
This event is triggered *before* an application handles a request. The actual event name is `beforeRequest`.
- [cache|CApplication::cache]: [CCache] - provides data caching
functionality. Note, you must specify the actual class (e.g.
[CMemCache], [CDbCache]). Otherwise, null will be returned when you
access this component.
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.
- [clientScript|CWebApplication::clientScript]: [CClientScript] -
manages client scripts (javascript and CSS).
- [coreMessages|CApplication::coreMessages]: [CPhpMessageSource] -
provides translated core messages used by the Yii framework.
### [[yii\base\Application::EVENT_BEFORE_REQUEST|EVENT_AFTER_REQUEST]]
- [db|CApplication::db]: [CDbConnection] - provides the database
connection. Note, you must configure its
[connectionString|CDbConnection::connectionString] property in order
to use this component.
This event is triggered *after* an application finishes handling a request but *before* sending the response.
The actual event name is `afterRequest`.
- [errorHandler|CApplication::errorHandler]: [CErrorHandler] - handles
uncaught PHP errors and exceptions.
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.
- [format|CApplication::format]: [CFormatter] - formats data values
for display purpose.
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.
- [messages|CApplication::messages]: [CPhpMessageSource] - provides
translated messages used by the Yii application.
- [request|CWebApplication::request]: [CHttpRequest] - provides
information related to user requests.
### [[yii\base\Application::EVENT_BEFORE_REQUEST|EVENT_BEFORE_ACTION]]
- [securityManager|CApplication::securityManager]: [CSecurityManager] -
provides security-related services, such as hashing and encryption.
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 {
}
},
]
```
- [session|CWebApplication::session]: [CHttpSession] - provides
session-related functionality.
Note that the same `beforeAction` event is also triggered by [modules](structure-modules.md)
and [controllers)(structure-controllers.md). Application objects are the first ones
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.
- [statePersister|CApplication::statePersister]: [CStatePersister] -
provides the mechanism for persisting global state.
- [urlManager|CWebApplication::urlManager]: [CUrlManager] - provides
URL parsing and creation functionality.
### [[yii\base\Application::EVENT_BEFORE_REQUEST|EVENT_AFTER_ACTION]]
- [user|CWebApplication::user]: [CWebUser] - carries identity-related
information about the current user.
This event is triggered *after* running every [controller action](structure-controllers.md).
The actual event name is `afterAction`.
- [themeManager|CWebApplication::themeManager]: [CThemeManager] - manages themes.
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,
```php
[
'on afterAction' => function ($event) {
if (some condition) {
// modify $event->result
} else {
}
},
]
```
## Application Lifecycle
Note that the same `afterAction` event is also triggered by [modules](structure-modules.md)
and [controllers)(structure-controllers.md). These objects trigger this event in the reverse order
as for that of `beforeAction`. That is, controllers are the first objects triggering this event,
followed by modules (if any), and finally applications.
When handling a user request, an application will undergo the following
life cycle:
## Application Components
Applications are [service locators](concept-service-locators.md). They host a set of the so-called
*application components* that provide different services for processing requests. For example,
the `urlManager` component is responsible for routing Web requests to appropriate controllers;
the `db` component provides DB-related services; and so on.
Each application component has an ID that uniquely identifies itself among other application components
in the same application. You can access an application component through the expression `$app->ID`,
where `$app` refers to an application instance, and `ID` stands for the ID of an application component.
For example, you can use `Yii::$app->db` to get the [[yii\db\Connection|DB connection]], and `Yii::$app->cache`
to get the [[yii\caching\Cache|primary cache]] registered with the application.
0. Pre-initialize the application with [CApplication::preinit()];
Application components can be any objects. You can register them with an application to make them
globally accessible. This is usually done by configuring the [[yii\base\Application::components]] property,
as described in the [components](#components) subsection.
Yii defines a set of *core* application components with fixed IDs and default configurations. For example,
the [[yii\web\Application::request|request]] component is used to collect information about
a user request and resolve it into a [route](runtime-routing.md); the [[yii\base\Application::db|db]]
component represents a database connection through which you can perform database queries.
It is with help of these core application components that Yii applications are able to handle user requests.
Below is the list of the predefined core application components. You may configure and customize them
like you do with normal application components. When you are configuring a core application component,
if you do not specify its class, the default one will be used.
* [[yii\web\AssetManager|assetManager]]: manages asset bundles and asset publishing.
Please refer to the [Managing Assets](output-assets.md) section for more details.
* [[yii\db\Connection|db]]: represents a database connection through which you can perform DB queries.
Note that when you configure this component, you must specify the component class as well as other required
component properties, such as [[yii\db\Connection::dsn]].
Please refer to the [Data Access Objects](db-dao.md) section for more details.
* [[yii\base\Application::errorHandler|errorHandler]]: handles PHP errors and exceptions.
Please refer to the [Handling Errors](tutorial-handling-errors.md) section for more details.
* [[yii\base\Formatter|formatter]]: formats data when they are displayed to end users. For example, a number
may be displayed with thousand separator, a date may be formatted in long format.
Please refer to the [Data Formatting](output-formatting.md) section for more details.
* [[yii\i18n\I18N|i18n]]: supports message translation and formatting.
Please refer to the [Internationalization](tutorial-i18n.md) section for more details.
* [[yii\log\Dispatcher|log]]: manages log targets.
Please refer to the [Logging](tutorial-logging.md) section for more details.
* [[yii\swiftmailer\Mailer|mail]]: supports mail composing and sending.
Please refer to the [Mailing](tutorial-mailing.md) section for more details.
* [[yii\base\Application::response|response]]: represents the response being sent to end users.
Please refer to the [Responses](runtime-responses.md) section for more details.
* [[yii\base\Application::request|request]]: represents the request received from end users.
Please refer to the [Requests](runtime-requests.md) section for more details.
* [[yii\web\Session|session]]: represents the session information. This component is only available
in [[yii\web\Application|Web applications]].
Please refer to the [Sessions and Cookies](runtime-sessions-cookies.md) section for more details.
* [[yii\web\UrlManager|urlManager]]: supports URL parsing and creation.
Please refer to the [URL Parsing and Generation](runtime-url-handling.md) section for more details.
* [[yii\web\User|user]]: represents the user authentication information. This component is only available
in [[yii\web\Application|Web applications]]
Please refer to the [Authentication](security-authentication.md) section for more details.
* [[yii\web\View|view]]: supports view rendering.
Please refer to the [Views](structure-views.md) section for more details.
## Application Lifecycle
1. Set up the error handling;
When an [entry script](structure-entry-scripts.md) is being executed to handle a request,
an application will undergo the following lifecycle:
2. Register core application components;
1. The entry script loads the application configuration as an array.
2. The entry script creates a new instance of the application:
3. Load application configuration;
2.1 [[yii\base\Application::preInit()|preInit()]] is called, which configures some high priority
application properties, such as [[yii\base\Application::basePath|basePath]].
2.2 Register the [[yii\base\Application::errorHandler|error handler]].
2.3 Configure application properties.
2.4 [[yii\base\Application::init()|init()]] is called which further calls
[[yii\base\Application::bootstrap()|bootstrap()]] to run bootstrap components.
4. Initialize the application with [CApplication::init()]
- Register application behaviors;
- Load static application components;
3. The entry script calls [[yii\base\Application::run()]] to run the application:
5. Raise an [onBeginRequest|CApplication::onBeginRequest] event;
3.1 Trigger the [[yii\base\Application::EVENT_BEFORE_REQUEST|EVENT_BEFORE_REQUEST]] event.
3.2 Handle the request:
6. Process the user request:
- Collect information about the request;
- Create a controller;
- Run the controller;
3.2.1 Resolve the request into a [route](runtime-routing.md) and the associated parameters.
3.2.2 Create the module, controller and action objects as specified by the route.
3.2.3 Run the action.
7. Raise an [onEndRequest|CApplication::onEndRequest] event;
3.3 Trigger the [[yii\base\Application::EVENT_AFTER_REQUEST|EVENT_AFTER_REQUEST]] event.
3.4 Send response to the end user.
4. The entry script receives the exit status from the application and completes the request processing.
framework/base/Module.php
......@@ -248,7 +248,7 @@ class Module extends ServiceLocator
/**
* Sets the directory that contains the layout files.
* @param string $path the root directory of layout files.
* @param string $path the root directory or path alias of layout files.
* @throws InvalidParamException if the directory is invalid
*/
public function setLayoutPath($path)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment