Configurations are widely used in Yii when creating new objects or initializing existing objects. Configurations usually include the class name of the object being created, and a list of initial values that should be assigned to the object's properties. Configurations may also include a list of handlers that should be attached to the object's events and/or a list of behaviors that should also be attached to the object.
In the following, a configuration is used to create and initialize a database connection:
$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 array as its argument, and creates an object by instantiating the class named in the configuration. When the object is instantiated, the rest of the configuration will be used to initialize the object's properties, event handlers, and behaviors.
If you already have an object, you may use Yii::configure() to initialize the object's properties with a configuration array:
Yii::configure($object, $config);
Note that, in this case, the configuration array should not contain a class
element.
The format of a configuration can be formally described as:
[
'class' => 'ClassName',
'propertyName' => 'propertyValue',
'on eventName' => $eventHandler,
'as behaviorName' => $behaviorConfig,
]
where
class
element specifies a fully qualified class name for the object being created.propertyName
elements specify the initial values for the named property. The keys are the property names, and the
values are the corresponding initial values. Only public member variables and properties
defined by getters/setters can be configured.on eventName
elements specify what handlers should be attached to the object's events.
Notice that the array keys are formed by prefixing event names with on
. Please refer to
the Events section for supported event handler formats.as behaviorName
elements specify what behaviors should be attached to the object.
Notice that the array keys are formed by prefixing behavior names with as
; the value, $behaviorConfig
, represents
the configuration for creating a behavior, like a normal configuration described here.Below is an example showing a configuration with initial property values, event handlers, and behaviors:
[
'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 ...
],
]
Configurations are used in many places in Yii. At the beginning of this section, we have shown how to create an object according to a configuration by using Yii::createObject(). In this subsection, we will describe application configurations and widget configurations - two major usages of configurations.
The configuration for an application is probably one of the most complex arrays in Yii. This is because the application class has a lot of configurable properties and events. More importantly, its 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 Project Template.
$config = [
'id' => 'basic',
'basePath' => dirname(__DIR__),
'extensions' => require __DIR__ . '/../vendor/yiisoft/extensions.php',
'components' => [
'cache' => [
'class' => 'yii\caching\FileCache',
],
'mailer' => [
'class' => 'yii\symfonymailer\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, where the class name is already given,
(new yii\web\Application($config))->run();
More details about configuring the components
property of an application can be found
in the Applications section and the Service Locator section.
Since version 2.0.11, the application configuration supports Dependency Injection Container
configuration using container
property. For example:
$config = [
'id' => 'basic',
'basePath' => dirname(__DIR__),
'extensions' => require __DIR__ . '/../vendor/yiisoft/extensions.php',
'container' => [
'definitions' => [
'yii\widgets\LinkPager' => ['maxButtonCount' => 5]
],
'singletons' => [
// Dependency Injection Container singletons configuration
]
]
];
To know more about the possible values of definitions
and singletons
configuration arrays and real-life examples,
please read Advanced Practical Usage subsection of the
Dependency Injection Container article.
When using widgets, you often need to use configurations to customize the widget properties. Both of the yii\base\Widget::widget() and yii\base\Widget::begin() methods can be used to create a widget. They take a configuration array, like the following,
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 activateItems
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.
When a configuration is very complex, a common practice is to store it in one or multiple PHP files, known as
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,
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,
return [
'cache' => [
'class' => 'yii\caching\FileCache',
],
'mailer' => [
'class' => 'yii\symfonymailer\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',
],
];
To get a configuration stored in a configuration file, simply "require" it, like the following:
$config = require 'path/to/web.php';
(new yii\web\Application($config))->run();
The Yii::createObject() method is implemented based on a dependency injection container.
It allows you to specify a set of the so-called default configurations which will be applied to ALL 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 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:
\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.
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 of your application.
For example,
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 in development environment.
$config = [...];
if (YII_ENV_DEV) {
// configuration adjustments for 'dev' environment
$config['bootstrap'][] = 'debug';
$config['modules']['debug'] = 'yii\debug\Module';
}
return $config;
Found a typo or you think this page needs improvement?
Edit it on github !
Signup or Login in order to comment.