From 80564a9a69012aa828e389e81d5ba9442806a962 Mon Sep 17 00:00:00 2001 From: Qiang Xue Date: Sat, 3 May 2014 15:15:29 -0400 Subject: [PATCH] fixed wrong file name. --- docs/guide/README.md | 2 +- docs/guide/basic-configs.md | 275 ----------------------------------- docs/guide/concept-aliases.md | 6 +- docs/guide/concept-behaviors.md | 2 +- docs/guide/concept-components.md | 2 +- docs/guide/concept-configurations.md | 275 +++++++++++++++++++++++++++++++++++ docs/guide/intro-upgrade-from-v1.md | 2 +- 7 files changed, 282 insertions(+), 282 deletions(-) delete mode 100644 docs/guide/basic-configs.md create mode 100644 docs/guide/concept-configurations.md diff --git a/docs/guide/README.md b/docs/guide/README.md index bc04eea..e8c54f5 100644 --- a/docs/guide/README.md +++ b/docs/guide/README.md @@ -57,7 +57,7 @@ Key Concepts * [Properties](concept-properties.md) * [Events](concept-events.md) * [Behaviors](concept-behaviors.md) -* [Configurations](concept-configs.md) +* [Configurations](concept-configurations.md) * [Aliases](concept-aliases.md) * [Class Autoloading](concept-autoloading.md) * [Service Locator](concept-service-locator.md) diff --git a/docs/guide/basic-configs.md b/docs/guide/basic-configs.md deleted file mode 100644 index 90b587e..0000000 --- a/docs/guide/basic-configs.md +++ /dev/null @@ -1,275 +0,0 @@ -Configurations -============== - -Configurations are widely used in Yii for creating new objects or initializing existing objects. -They usually include the class names of the objects being created and a list of initial values -that should be assigned to object [properties](concept-properties.md). They may also include a list of -handlers that should be attached to the object [events](concept-events.md), and/or a list of -[behaviors](concept-behaviors.md) that should be attached to the objects. - -In the following, a configuration is used to create and initialize a DB connection: - -```php -$config = [ - 'class' => 'yii\db\Connection', - 'dsn' => 'mysql:host=127.0.0.1;dbname=demo', - 'username' => 'root', - 'password' => '', - 'charset' => 'utf8', -]; - -$db = Yii::createObject($config); -``` - -The [[Yii::createObject()]] method takes a configuration and creates an object based on the class name -specified in the configuration. When the object is being instantiated, the rest of the configuration -will be used to initialize the object properties, event handlers and/or behaviors. - -If you already have an object, you may use [[Yii::configure()]] to initialize the object properties with -a configuration, like the following, - -```php -Yii::configure($object, $config); -``` - -Note that in this case, the configuration should not contain the `class` element. - - -Configuration Format --------------------- - -The format of a configuration can be formally described as follows, - -```php -[ - 'class' => 'ClassName', - 'propertyName' => 'propertyValue', - 'on eventName' => $eventHandler, - 'as behaviorName' => $behaviorConfig, -] -``` - -where - -* The `class` element specifies a fully qualified class name for the object being created. -* The `propertyName` elements specify the property initial values. The keys are the property names, and the - values are the corresponding initial values. Only public member variables and [properties](concept-properties.md) - defined by getters/setters can be configured. -* The `on eventName` elements specify what handlers should be attached to the object [events](concept-events.md). - Notice that the array keys are formed by prefixing event names with `on `. Please refer to - the [Events](concept-events.md) chapter for supported event handler formats. -* And the `as behaviorName` elements specify what [behaviors](concept-behaviors.md) should be attached to the object. - Notice that the array keys are formed by prefixing behavior names with `on `. `$behaviorConfig` represents - the configuration for creating a behavior, like a normal configuration as we are describing here. - -Below is an example showing a configuration with property initial values, event handlers and behaviors: - -```php -[ - 'class' => 'app\components\SearchEngine', - 'apiKey' => 'xxxxxxxx', - 'on search' => function ($event) { - Yii::info("Keyword searched: " . $event->keyword); - }, - 'as indexer' => [ - 'class' => 'app\components\IndexerBehavior', - // ... property init values ... - ], -] -``` - - -Using Configurations --------------------- - -Configurations are used in many places in Yii. At the beginning of this chapter, we have shown how to use -create an object according to a configuration by using [[Yii::createObject()]]. In this section, we will -describe application configurations and widget configurations - two major usages of configurations. - - -### Application Configurations - -Configuration for an [application](structure-applications.md) is probably one of the most complex configurations. -This is because the [[yii\web\Application|application]] class has a lot of configurable properties and events. -More importantly, its [[yii\web\Application::components|components]] property can receive an array of configurations -for creating components that are registered through the application. The following is an abstract from the application -configuration file for the [basic application template](start-basic.md). - -```php -$config = [ - 'id' => 'basic', - 'basePath' => dirname(__DIR__), - 'extensions' => require(__DIR__ . '/../vendor/yiisoft/extensions.php'), - 'components' => [ - 'cache' => [ - 'class' => 'yii\caching\FileCache', - ], - 'mail' => [ - 'class' => 'yii\swiftmailer\Mailer', - ], - 'log' => [ - 'class' => 'yii\log\Dispatcher', - 'traceLevel' => YII_DEBUG ? 3 : 0, - 'targets' => [ - [ - 'class' => 'yii\log\FileTarget', - ], - ], - ], - 'db' => [ - 'class' => 'yii\db\Connection', - 'dsn' => 'mysql:host=localhost;dbname=stay2', - 'username' => 'root', - 'password' => '', - 'charset' => 'utf8', - ], - ], -]; -``` - -The configuration does not have a `class` key. This is because it is used as follows in -an [entry script](structure-entry-scripts.md), where the class name is already given, - -```php -(new yii\web\Application($config))->run(); -``` - -For more details about configuring the `components` property of an application can be found -in the [Applications](structure-applications.md) chapter and the [Service Locator](concept-service-locator.md) chapter. - - -### Widget Configurations - -When using [widgets](structure-widgets.md), you often need to use configurations to customize the widget properties. -Both of the [[yii\base\Widget::widget()]] and [[yii\base\Widget::beginWidget()]] methods can be used to create -a widget. They take a configuration array, like the following, - -```php -use yii\widgets\Menu; - -echo Menu::widget([ - 'activateItems' => false, - 'items' => [ - ['label' => 'Home', 'url' => ['site/index']], - ['label' => 'Products', 'url' => ['product/index']], - ['label' => 'Login', 'url' => ['site/login'], 'visible' => Yii::$app->user->isGuest], - ], -]); -``` - -The above code creates a `Menu` widget and initializes its `activeItems` property to be false. -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 -------------------- - -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. -For example, you may keep an application configuration in a file named `web.php`, like the following, - -```php -return [ - 'id' => 'basic', - 'basePath' => dirname(__DIR__), - 'extensions' => require(__DIR__ . '/../vendor/yiisoft/extensions.php'), - 'components' => require(__DIR__ . '/components.php'), -]; -``` - -Because the `components` configuration is complex too, you store it in a separate file called `components.php` -and "require" this file in `web.php` as shown above. The content of `components.php` is as follows, - -```php -return [ - 'cache' => [ - 'class' => 'yii\caching\FileCache', - ], - 'mail' => [ - 'class' => 'yii\swiftmailer\Mailer', - ], - 'log' => [ - 'class' => 'yii\log\Dispatcher', - 'traceLevel' => YII_DEBUG ? 3 : 0, - 'targets' => [ - [ - 'class' => 'yii\log\FileTarget', - ], - ], - ], - 'db' => [ - 'class' => 'yii\db\Connection', - 'dsn' => 'mysql:host=localhost;dbname=stay2', - 'username' => 'root', - 'password' => '', - 'charset' => 'utf8', - ], -]; -``` - -And the code for starting an application becomes, - -```php -$config = require('path/to/web.php'); -(new yii\web\Application($config))->run(); -``` - - -Default Configurations ----------------------- - -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 -the specified classes when they are being created using [[Yii::createObject()]]. The default configurations -can be specified by calling `Yii::$container->set()` in the [bootstrapping](runtime-bootstrapping.md) code. - -For example, if you want to customize [[yii\widgets\LinkPager]] so that ALL link pagers will show at most 5 page buttons -(the default value is 10), you may use the following code to achieve this goal, - -```php -\Yii::$container->set('yii\widgets\LinkPager', [ - 'maxButtonCount' => 5, -]); -``` - -Without using default configurations, you would have to configure `maxButtonCount` in every place where you use -link pagers. - - -Environment Constants ---------------------- - -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 -you may want to use the `mydb_prod` database. To facilitate switching environments, Yii provides a constant -named `YII_ENV` that you may define in the [entry script](structure-entry-scripts.md) of your application. -For example, - -```php -defined('YII_ENV') or define('YII_ENV', 'dev'); -``` - -You may define `YII_ENV` as one of the following values: - -- `prod`: production environment. The constant `YII_ENV_PROD` will evaluate as true. - This is the default value of `YII_ENV` if you do not define it. -- `dev`: development environment. The constant `YII_ENV_DEV` will evaluate as true. -- `test`: testing environment. The constant `YII_ENV_TEST` will evaluate as true. - -With these environment constants, you may specify your configurations conditionally based on -the current environment. For example, your application configuration may contain the following -code to enable the [debug toolbar and debugger](tool-debugger.md) in development environment. - -```php -$config = [...]; - -if (YII_ENV_DEV) { - // configuration adjustments for 'dev' environment - $config['bootstrap'][] = 'debug'; - $config['modules']['debug'] = 'yii\debug\Module'; -} - -return $config; -``` diff --git a/docs/guide/concept-aliases.md b/docs/guide/concept-aliases.md index ab2c9fa..2856157 100644 --- a/docs/guide/concept-aliases.md +++ b/docs/guide/concept-aliases.md @@ -35,8 +35,8 @@ Yii::setAlias('@foobar', '@foo/bar'); Root aliases are usually defined during the [bootstrapping](runtime-bootstrapping.md) stage. For example, you may call [[Yii::setAlias()]] in the [entry script](structure-entry-scripts.md). -For convenience, [Application](structure-applications.md) provides writable property named `aliases` -that you can configure in the application [configuration](concept-configs.md), like the following, +For convenience, [Application](structure-applications.md) provides a writable property named `aliases` +that you can configure in the application [configuration](concept-configurations.md), like the following, ```php return [ @@ -115,7 +115,7 @@ The following is the list of the predefined aliases: The `@yii` alias is defined when you include the `Yii.php` file in your [entry script](structure-entry-scripts.md), while the rest of the aliases are defined in the application constructor when applying the application -[configuration](concept-configs.md). +[configuration](concept-configurations.md). Extension Aliases diff --git a/docs/guide/concept-behaviors.md b/docs/guide/concept-behaviors.md index dd5d8ca..e2e38bb 100644 --- a/docs/guide/concept-behaviors.md +++ b/docs/guide/concept-behaviors.md @@ -98,7 +98,7 @@ class User extends ActiveRecord } ``` -The [[yii\base\Component::behaviors()|behaviors()]] method should return a list of behavior [configurations](concept-configs.md). +The [[yii\base\Component::behaviors()|behaviors()]] method should return a list of behavior [configurations](concept-configurations.md). Each behavior configuration can be either a behavior class name or a configuration array. You may associate a name with a behavior by specifying the array key corresponding to the behavior configuration. diff --git a/docs/guide/concept-components.md b/docs/guide/concept-components.md index 9b2b4c4..92a2362 100644 --- a/docs/guide/concept-components.md +++ b/docs/guide/concept-components.md @@ -61,7 +61,7 @@ class MyClass extends Object } ``` -This will make your components [configurable](concept-configs.md) when they are being created. For example, +This will make your components [configurable](concept-configurations.md) when they are being created. For example, ```php $component = new MyClass(1, 2, ['prop1' => 3, 'prop2' => 4]); diff --git a/docs/guide/concept-configurations.md b/docs/guide/concept-configurations.md new file mode 100644 index 0000000..90b587e --- /dev/null +++ b/docs/guide/concept-configurations.md @@ -0,0 +1,275 @@ +Configurations +============== + +Configurations are widely used in Yii for creating new objects or initializing existing objects. +They usually include the class names of the objects being created and a list of initial values +that should be assigned to object [properties](concept-properties.md). They may also include a list of +handlers that should be attached to the object [events](concept-events.md), and/or a list of +[behaviors](concept-behaviors.md) that should be attached to the objects. + +In the following, a configuration is used to create and initialize a DB connection: + +```php +$config = [ + 'class' => 'yii\db\Connection', + 'dsn' => 'mysql:host=127.0.0.1;dbname=demo', + 'username' => 'root', + 'password' => '', + 'charset' => 'utf8', +]; + +$db = Yii::createObject($config); +``` + +The [[Yii::createObject()]] method takes a configuration and creates an object based on the class name +specified in the configuration. When the object is being instantiated, the rest of the configuration +will be used to initialize the object properties, event handlers and/or behaviors. + +If you already have an object, you may use [[Yii::configure()]] to initialize the object properties with +a configuration, like the following, + +```php +Yii::configure($object, $config); +``` + +Note that in this case, the configuration should not contain the `class` element. + + +Configuration Format +-------------------- + +The format of a configuration can be formally described as follows, + +```php +[ + 'class' => 'ClassName', + 'propertyName' => 'propertyValue', + 'on eventName' => $eventHandler, + 'as behaviorName' => $behaviorConfig, +] +``` + +where + +* The `class` element specifies a fully qualified class name for the object being created. +* The `propertyName` elements specify the property initial values. The keys are the property names, and the + values are the corresponding initial values. Only public member variables and [properties](concept-properties.md) + defined by getters/setters can be configured. +* The `on eventName` elements specify what handlers should be attached to the object [events](concept-events.md). + Notice that the array keys are formed by prefixing event names with `on `. Please refer to + the [Events](concept-events.md) chapter for supported event handler formats. +* And the `as behaviorName` elements specify what [behaviors](concept-behaviors.md) should be attached to the object. + Notice that the array keys are formed by prefixing behavior names with `on `. `$behaviorConfig` represents + the configuration for creating a behavior, like a normal configuration as we are describing here. + +Below is an example showing a configuration with property initial values, event handlers and behaviors: + +```php +[ + 'class' => 'app\components\SearchEngine', + 'apiKey' => 'xxxxxxxx', + 'on search' => function ($event) { + Yii::info("Keyword searched: " . $event->keyword); + }, + 'as indexer' => [ + 'class' => 'app\components\IndexerBehavior', + // ... property init values ... + ], +] +``` + + +Using Configurations +-------------------- + +Configurations are used in many places in Yii. At the beginning of this chapter, we have shown how to use +create an object according to a configuration by using [[Yii::createObject()]]. In this section, we will +describe application configurations and widget configurations - two major usages of configurations. + + +### Application Configurations + +Configuration for an [application](structure-applications.md) is probably one of the most complex configurations. +This is because the [[yii\web\Application|application]] class has a lot of configurable properties and events. +More importantly, its [[yii\web\Application::components|components]] property can receive an array of configurations +for creating components that are registered through the application. The following is an abstract from the application +configuration file for the [basic application template](start-basic.md). + +```php +$config = [ + 'id' => 'basic', + 'basePath' => dirname(__DIR__), + 'extensions' => require(__DIR__ . '/../vendor/yiisoft/extensions.php'), + 'components' => [ + 'cache' => [ + 'class' => 'yii\caching\FileCache', + ], + 'mail' => [ + 'class' => 'yii\swiftmailer\Mailer', + ], + 'log' => [ + 'class' => 'yii\log\Dispatcher', + 'traceLevel' => YII_DEBUG ? 3 : 0, + 'targets' => [ + [ + 'class' => 'yii\log\FileTarget', + ], + ], + ], + 'db' => [ + 'class' => 'yii\db\Connection', + 'dsn' => 'mysql:host=localhost;dbname=stay2', + 'username' => 'root', + 'password' => '', + 'charset' => 'utf8', + ], + ], +]; +``` + +The configuration does not have a `class` key. This is because it is used as follows in +an [entry script](structure-entry-scripts.md), where the class name is already given, + +```php +(new yii\web\Application($config))->run(); +``` + +For more details about configuring the `components` property of an application can be found +in the [Applications](structure-applications.md) chapter and the [Service Locator](concept-service-locator.md) chapter. + + +### Widget Configurations + +When using [widgets](structure-widgets.md), you often need to use configurations to customize the widget properties. +Both of the [[yii\base\Widget::widget()]] and [[yii\base\Widget::beginWidget()]] methods can be used to create +a widget. They take a configuration array, like the following, + +```php +use yii\widgets\Menu; + +echo Menu::widget([ + 'activateItems' => false, + 'items' => [ + ['label' => 'Home', 'url' => ['site/index']], + ['label' => 'Products', 'url' => ['product/index']], + ['label' => 'Login', 'url' => ['site/login'], 'visible' => Yii::$app->user->isGuest], + ], +]); +``` + +The above code creates a `Menu` widget and initializes its `activeItems` property to be false. +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 +------------------- + +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. +For example, you may keep an application configuration in a file named `web.php`, like the following, + +```php +return [ + 'id' => 'basic', + 'basePath' => dirname(__DIR__), + 'extensions' => require(__DIR__ . '/../vendor/yiisoft/extensions.php'), + 'components' => require(__DIR__ . '/components.php'), +]; +``` + +Because the `components` configuration is complex too, you store it in a separate file called `components.php` +and "require" this file in `web.php` as shown above. The content of `components.php` is as follows, + +```php +return [ + 'cache' => [ + 'class' => 'yii\caching\FileCache', + ], + 'mail' => [ + 'class' => 'yii\swiftmailer\Mailer', + ], + 'log' => [ + 'class' => 'yii\log\Dispatcher', + 'traceLevel' => YII_DEBUG ? 3 : 0, + 'targets' => [ + [ + 'class' => 'yii\log\FileTarget', + ], + ], + ], + 'db' => [ + 'class' => 'yii\db\Connection', + 'dsn' => 'mysql:host=localhost;dbname=stay2', + 'username' => 'root', + 'password' => '', + 'charset' => 'utf8', + ], +]; +``` + +And the code for starting an application becomes, + +```php +$config = require('path/to/web.php'); +(new yii\web\Application($config))->run(); +``` + + +Default Configurations +---------------------- + +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 +the specified classes when they are being created using [[Yii::createObject()]]. The default configurations +can be specified by calling `Yii::$container->set()` in the [bootstrapping](runtime-bootstrapping.md) code. + +For example, if you want to customize [[yii\widgets\LinkPager]] so that ALL link pagers will show at most 5 page buttons +(the default value is 10), you may use the following code to achieve this goal, + +```php +\Yii::$container->set('yii\widgets\LinkPager', [ + 'maxButtonCount' => 5, +]); +``` + +Without using default configurations, you would have to configure `maxButtonCount` in every place where you use +link pagers. + + +Environment Constants +--------------------- + +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 +you may want to use the `mydb_prod` database. To facilitate switching environments, Yii provides a constant +named `YII_ENV` that you may define in the [entry script](structure-entry-scripts.md) of your application. +For example, + +```php +defined('YII_ENV') or define('YII_ENV', 'dev'); +``` + +You may define `YII_ENV` as one of the following values: + +- `prod`: production environment. The constant `YII_ENV_PROD` will evaluate as true. + This is the default value of `YII_ENV` if you do not define it. +- `dev`: development environment. The constant `YII_ENV_DEV` will evaluate as true. +- `test`: testing environment. The constant `YII_ENV_TEST` will evaluate as true. + +With these environment constants, you may specify your configurations conditionally based on +the current environment. For example, your application configuration may contain the following +code to enable the [debug toolbar and debugger](tool-debugger.md) in development environment. + +```php +$config = [...]; + +if (YII_ENV_DEV) { + // configuration adjustments for 'dev' environment + $config['bootstrap'][] = 'debug'; + $config['modules']['debug'] = 'yii\debug\Module'; +} + +return $config; +``` diff --git a/docs/guide/intro-upgrade-from-v1.md b/docs/guide/intro-upgrade-from-v1.md index 88f5794..62b9f98 100644 --- a/docs/guide/intro-upgrade-from-v1.md +++ b/docs/guide/intro-upgrade-from-v1.md @@ -105,7 +105,7 @@ $object = Yii::createObject([ ], [$param1, $param2]); ``` -More details about configurations can be found in the [Object Configurations](concept-configs.md) chapter. +More details about configurations can be found in the [Object Configurations](concept-configurations.md) chapter. Events