Commit 4b6b9d41 by Qiang Xue

guide WIP [skip ci]

parent d5329954
......@@ -35,8 +35,7 @@ Yii::configure($object, $config);
Note that in this case, the configuration should not contain the `class` element.
Configuration Format <a name="configuration-format"></a>
--------------------
## Configuration Format <a name="configuration-format"></a>
The format of a configuration can be formally described as follows,
......@@ -79,8 +78,7 @@ Below is an example showing a configuration with property initial values, event
```
Using Configurations <a name="using-configurations"></a>
--------------------
## Using Configurations <a name="using-configurations"></a>
Configurations are used in many places in Yii. At the beginning of this section, we have shown how to use
create an object according to a configuration by using [[Yii::createObject()]]. In this subsection, we will
......@@ -163,11 +161,10 @@ The `items` property is also configured with menu items to be displayed.
Note that because the class name is already given, the configuration array should NOT have the `class` key.
Configuration Files <a name="configuration-files"></a>
-------------------
## Configuration Files <a name="configuration-files"></a>
When a configuration is very complex, a common practice is to store it in one or multiple PHP files, known as
*configuration files*. To use a configuration, simply "require" the corresponding configuration file.
*configuration files*. A configuration file returns a PHP array representing the configuration.
For example, you may keep an application configuration in a file named `web.php`, like the following,
```php
......@@ -209,7 +206,7 @@ return [
];
```
And the code for starting an application becomes,
To get a configuration stored in a configuration file, simply "require" it, like the following:
```php
$config = require('path/to/web.php');
......@@ -217,8 +214,7 @@ $config = require('path/to/web.php');
```
Default Configurations <a name="default-configurations"></a>
----------------------
## Default Configurations <a name="default-configurations"></a>
The [[Yii::createObject()]] method is implemented based on a [dependency injection container](concept-di-container.md).
It allows you specify a set of the so-called *default configurations* which will be applied to ANY instances of
......@@ -238,8 +234,7 @@ Without using default configurations, you would have to configure `maxButtonCoun
link pagers.
Environment Constants <a name="environment-constants"></a>
---------------------
## Environment Constants <a name="environment-constants"></a>
Configurations often vary according to the environment in which an application runs. For example,
in development environment, you may want to use a database named `mydb_dev`, while on production server
......
Applications
============
Applications represent execution contexts within which requests are being processed.
The main task of applications is to analyze requests and dispatch them to appropriate
[controllers](structure-controllers.md) for further processing. For this reason, applications
are also called *front controllers*.
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`.
There are two main types of applications: [[yii\web\Application|Web applications]] and
> 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
[[yii\console\Application|console applications]]. As the names indicate, the former mainly handles
Web requests while the latter console command requests.
Applications are usually instantiated in [entry scripts](structure-entry-scripts.md) and can be globally accessed
via the expression `Yii::$app`.
## Configurations
## Application Configurations
When applications are being instantiated in [entry scripts](structure-entry-scripts.md), they
need to be configured to well describe the execution contexts. For example, the applications need
to know where to look for controller classes, where to store temporary files, etc. These information
are typically represented in terms of [configurations](concept-configurations.md) and stored in
one or multiple configuration files, called application configuration files.
The following code in an entry script shows how an application instance is created and configured using
the configuration loaded from a configuration file `web.php`:
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:
```php
require(__DIR__ . '/../vendor/autoload.php');
......@@ -36,6 +29,151 @@ $config = require(__DIR__ . '/../config/web.php');
(new yii\web\Application($config))->run();
```
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.
## Application Properties
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.
### Required Properties
In any application, you should at least configure two properties: [[yii\base\Application::id|id]]
and [[yii\base\Application::basePath|basePath]].
####
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.
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).
### Important Properties
You usually will configure the properties as their values differ across different applications.
#### [[yii\base\Application::aliases|aliases]]
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()]].
#### [[yii\base\Application::bootstrap|bootstrap]]
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.
For example,
```php
[
'bootstrap' => [
// an application component ID or module ID
'demo',
// a class name
'app\components\TrafficMonitor',
// a configuration array
[
'class' => 'app\components\Profiler',
'level' => 3,
]
],
]
```
During the bootstrapping process, each component will be instantiated. If the component class
implements [[yii\base\BootstrapInterface]], its [[yii\base\BootstrapInterface::bootstrap()|bootstrap()]] method
will be also be called.
#### [[yii\base\Application::components|components]]
#### [[yii\base\Application::controllerMap|controllerMap]]
#### [[yii\base\Application::controllerNamespace|controllerNamespace]]
#### [[yii\base\Application::language|language]]
#### [[yii\base\Application::modules|modules]]
#### [[yii\base\Application::name|name]]
#### [[yii\base\Application::params|params]]
#### [[yii\base\Application::version|version]]
### Useful Properties
#### [[yii\base\Application::layoutPath|layoutPath]]
#### [[yii\base\Application::runtimePath|runtimePath]]
#### [[yii\base\Application::viewPath|viewPath]]
#### [[yii\base\Application::vendorPath|vendorPath]]
#### [[yii\base\Application::timeZone|timeZone]]
#### [[yii\base\Application::layout|layout]]
#### [[yii\base\Application::defaultRoute|defaultRoute]]
#### [[yii\base\Application::charset|charset]]
#### [[yii\base\Application::sourceLanguage|sourceLanguage]]
#### [[yii\base\Application::extensions|extensions]]
// WEB
public $catchAll;
// Console
public $enableCoreCommands = true;
## Application Components
......
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