From ad31cf6fd2f366d1328bf761c39e7ee3897bcf28 Mon Sep 17 00:00:00 2001 From: Qiang Xue Date: Thu, 1 May 2014 22:08:16 -0400 Subject: [PATCH] Finished configuration chapter. --- docs/guide/README.md | 1 + docs/guide/basic-components.md | 46 +++++++ docs/guide/basic-configs.md | 294 +++++++++++++++++++++++------------------ docs/guide/structure-entry.md | 31 +++++ 4 files changed, 242 insertions(+), 130 deletions(-) create mode 100644 docs/guide/basic-components.md create mode 100644 docs/guide/structure-entry.md diff --git a/docs/guide/README.md b/docs/guide/README.md index 6dd0f47..7ac9dd0 100644 --- a/docs/guide/README.md +++ b/docs/guide/README.md @@ -27,6 +27,7 @@ Getting Started Basic Concepts -------------- +* [Components](basic-components.md) * [Properties](basic-properties.md) * [Events](basic-events.md) * [Behaviors](basic-behaviors.md) diff --git a/docs/guide/basic-components.md b/docs/guide/basic-components.md new file mode 100644 index 0000000..f8115fe --- /dev/null +++ b/docs/guide/basic-components.md @@ -0,0 +1,46 @@ +Components +========== + +> Note: This chapter is under development. + + +Object Configuration +-------------------- + +The [[yii\base\Object|Object]] class introduces a uniform way of configuring objects. Any descendant class +of [[yii\base\Object|Object]] should declare its constructor (if needed) in the following way so that +it can be properly configured: + +```php +class MyClass extends \yii\base\Object +{ + public function __construct($param1, $param2, $config = []) + { + // ... initialization before configuration is applied + + parent::__construct($config); + } + + public function init() + { + parent::init(); + + // ... initialization after configuration is applied + } +} +``` + +In the above example, the last parameter of the constructor must take a configuration array +which contains name-value pairs that will be used to initialize the object's properties at the end of the constructor. +You can override the `init()` method to do initialization work after the configuration is applied. + +By following this convention, you will be able to create and configure new objects +using a configuration array like the following: + +```php +$object = Yii::createObject([ + 'class' => 'MyClass', + 'property1' => 'abc', + 'property2' => 'cde', +], [$param1, $param2]); +``` diff --git a/docs/guide/basic-configs.md b/docs/guide/basic-configs.md index b6f47d2..faacdc4 100644 --- a/docs/guide/basic-configs.md +++ b/docs/guide/basic-configs.md @@ -1,204 +1,238 @@ -Configuration -============= +Configurations +============== -> Note: This chapter is under development. +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](basic-properties.md). They may also include a list of +handlers that should be attached to the object [events](basic-events.md), and/or a list of +[behaviors](basic-behaviors.md) that should be attached to the objects. -Object Configuration --------------------- - -The [[yii\base\Object|Object]] class introduces a uniform way of configuring objects. Any descendant class -of [[yii\base\Object|Object]] should declare its constructor (if needed) in the following way so that -it can be properly configured: +In the following, a configuration is used to create and initialize a DB connection: ```php -class MyClass extends \yii\base\Object -{ - public function __construct($param1, $param2, $config = []) - { - // ... initialization before configuration is applied - - parent::__construct($config); - } - - public function init() - { - parent::init(); - - // ... initialization after configuration is applied - } -} +$config = [ + 'class' => 'yii\db\Connection', + 'dsn' => 'mysql:host=127.0.0.1;dbname=demo', + 'username' => 'root', + 'password' => '', + 'charset' => 'utf8', +]; + +$db = Yii::createObject($config); ``` -In the above example, the last parameter of the constructor must take a configuration array -which contains name-value pairs that will be used to initialize the object's properties at the end of the constructor. -You can override the `init()` method to do initialization work after the configuration is applied. +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. -By following this convention, you will be able to create and configure new objects -using a configuration array like the following: +If you already have an object, you may use [[Yii::configure()]] to initialize the object properties with +a configuration, like the following, ```php -$object = Yii::createObject([ - 'class' => 'MyClass', - 'property1' => 'abc', - 'property2' => 'cde', -], [$param1, $param2]); +Yii::configure($object, $config); ``` +Note that in this case, the configuration should not contain the `class` element. -Yii applications rely upon components to perform most of the common tasks, such as connecting to a database, routing browser -requests, and handling sessions. How these stock components behave can be adjusted by *configuring* your Yii application. -The majority of components have sensible default settings, so it's unlikely that you'll do a lot of configuration. Still, there are some mandatory configuration settings that you will have to establish, such as the database connection. - -How an application is configured depends upon the application template in use, but there are some general principles that apply in every Yii case. - -Configuring options in the bootstrap file ------------------------------------------ - -For each application in Yii there is at least one bootstrap file: a PHP script through which all requests are handled. For web applications, the bootstrap file is typically `index.php`; for -console applications, the bootstrap file is `yii`. Both bootstrap files perform nearly the same job: -1. Setting common constants. -2. Including the Yii framework itself. -3. Including [Composer autoloader](http://getcomposer.org/doc/01-basic-usage.md#autoloading). -4. Reading the configuration file into `$config`. -5. Creating a new application instance, configured via `$config`, and running that instance. - -Like any resource in your Yii application, the bootstrap file can be edited to fit your needs. A typical change is to the value of `YII_DEBUG`. This constant should be `true` during development, but always `false` on production sites. +Configuration Format +-------------------- -The default bootstrap structure sets `YII_DEBUG` to `false` if not defined: +The format of a configuration can be formally described as follows, ```php -defined('YII_DEBUG') or define('YII_DEBUG', false); +[ + 'class' => 'ClassName', + 'propertyName' => 'propertyValue', + 'on eventName' => $eventHandler, + 'as behaviorName' => $behaviorConfig, +] ``` -During development, you can change this to `true`: - -```php -define('YII_DEBUG', true); // Development only -defined('YII_DEBUG') or define('YII_DEBUG', false); -``` +where -Configuring the application instance ------------------------------------- +* 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](basic-properties.md) + defined by getters/setters can be configured. +* The `on eventName` elements specify what handlers should be attached to the object [events](basic-events.md). + Notice that the array keys are formed by prefixing event names with `on `. Please refer to + the [Events](basic-events.md) chapter for supported event handler formats. +* And the `as behaviorName` elements specify what [behaviors](basic-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. -An application instance is configured when it's created in the bootstrap file. The configuration is typically -stored in a PHP file stored in the `/config` application directory. The file has this structure to begin: +Below is an example showing a configuration with property initial values, event handlers and behaviors: ```php - 'applicationId', - 'basePath' => dirname(__DIR__), - 'components' => [ - // configuration of application components goes here... +[ + '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 ... ], - 'params' => require(__DIR__ . '/params.php'), -]; +] ``` -The configuration is a large array of key-value pairs. In the above, the array keys are the names of application properties. Depending upon the application type, you can configure the properties of -either [[yii\web\Application]] or [[yii\console\Application]] classes. Both classes extend [[yii\base\Application]]. -Note that you can configure not only public class properties, but any property accessible via a setter. For example, to - configure the runtime path, you can use a key named `runtimePath`. There's no such property in the application class, but - since the class has a corresponding setter named `setRuntimePath`, `runtimePath` becomes configurable. - The ability to configure properties via setters is available to any class that extends from [[yii\base\Object]], which is nearly every class in the Yii framework. +Using Configurations +-------------------- -Configuring application components ----------------------------------- +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. -The majority of the Yii functionality comes from application components. These components are attached to the application instance via the instance's `components` property: + +### 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 - 'applicationId', +$config = [ + 'id' => 'basic', 'basePath' => dirname(__DIR__), + 'extensions' => require(__DIR__ . '/../vendor/yiisoft/extensions.php'), 'components' => [ - 'cache' => ['class' => 'yii\caching\FileCache'], - 'user' => ['identityClass' => 'app\models\User'], - 'errorHandler' => ['errorAction' => 'site/error'], + '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', - 'levels' => ['error', 'warning'], ], ], ], + 'db' => [ + 'class' => 'yii\db\Connection', + 'dsn' => 'mysql:host=localhost;dbname=stay2', + 'username' => 'root', + 'password' => '', + 'charset' => 'utf8', + ], ], - // ... ]; ``` -In the above code, four components are configured: `cache`, `user`, `errorHandler`, `log`. Each entry's key is a component ID. The values are subarrays used to configure that component. The component ID is also used to access the component anywhere within the application, using code like `\Yii::$app->myComponent`. +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, -The configuration array has one special key named `class` that identifies the component's base class. The rest of the keys and values are used -to configure component properties in the same way as top-level keys are used to configure the application's properties. +```php +(new yii\web\Application($config))->run(); +``` -Each application has a predefined set of components. To configure one of these, the `class` key can be omitted to use the default Yii class for that component. You can check the `coreComponents()` method of the application you are using -to get a list of component IDs and corresponding classes. +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](basic-service-locator.md) chapter. -Note that Yii is smart enough to only configure the component when it's actually being used: for example, if you configure the `cache` component in your configuration file but never use the `cache` component in your code, no instance of that component will be created and no time is wasted configuring it. -Setting component defaults class-wide ------------------------------------- +### Widget Configurations -For each component you can specify class-wide defaults. For example, if you want to change the class used for all `LinkPager` -widgets without specifying the class for every widget usage, you can do the following: +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 -\Yii::$container->set('yii\widgets\LinkPager', [ - 'options' => [ - 'class' => 'pagination', +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 code above should be executed once before `LinkPager` widget is used. It can be done in `index.php`, the application -configuration file, or anywhere else. +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. -### Attaching event handlers via config +Configuration Files +------------------- -You can also attach event handlers within your configuration file. To do so, add an element to the component to which the handler should be attached. The syntax is `"on " => handler`: +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 [ - // ... - 'components' => [ - 'db' => [ - // ... - 'on afterOpen' => function ($event) { - // do something right after connected to database - } - ], - ], + 'id' => 'basic', + 'basePath' => dirname(__DIR__), + 'extensions' => require(__DIR__ . '/../vendor/yiisoft/extensions.php'), + 'components' => require(__DIR__ . '/components.php'), ]; ``` - -### Attaching behaviors from config - -One can attach a behavior to a component when configuring it with a configuration array. The syntax is like the -following: +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 [ - // ... - 'components' => [ - 'myComponent' => [ - // ... - 'as tree' => [ - 'class' => 'Tree', - 'root' => 0, + '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', + ], ]; ``` -In the config above `as tree` stands for attaching a behavior named `tree`, and the array will be passed to [[\Yii::createObject()]] -to create the behavior object. +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](basic-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. diff --git a/docs/guide/structure-entry.md b/docs/guide/structure-entry.md new file mode 100644 index 0000000..c8d3d52 --- /dev/null +++ b/docs/guide/structure-entry.md @@ -0,0 +1,31 @@ +Entry Scripts +============= + +> Note: This chapter is under development. + +Configuring options in the bootstrap file +----------------------------------------- + +For each application in Yii there is at least one bootstrap file: a PHP script through which all requests are handled. For web applications, the bootstrap file is typically `index.php`; for +console applications, the bootstrap file is `yii`. Both bootstrap files perform nearly the same job: + +1. Setting common constants. +2. Including the Yii framework itself. +3. Including [Composer autoloader](http://getcomposer.org/doc/01-basic-usage.md#autoloading). +4. Reading the configuration file into `$config`. +5. Creating a new application instance, configured via `$config`, and running that instance. + +Like any resource in your Yii application, the bootstrap file can be edited to fit your needs. A typical change is to the value of `YII_DEBUG`. This constant should be `true` during development, but always `false` on production sites. + +The default bootstrap structure sets `YII_DEBUG` to `false` if not defined: + +```php +defined('YII_DEBUG') or define('YII_DEBUG', false); +``` + +During development, you can change this to `true`: + +```php +define('YII_DEBUG', true); // Development only +defined('YII_DEBUG') or define('YII_DEBUG', false); +```