Конфигурации

Конфигурации широко используются в Yii при создании новых объектов или при инициализации уже существующих объектов. Обычно конфигурации включают в себя названия классов создаваемых объектов и список первоначальных значений, которые должны быть присвоены свойствам объекта. Также в конфигурациях можно указать список обработчиков событий объекта, и/или список поведений объекта.

Пример конфигурации подключения к базе данных и дальнейшей инициализации подключения:

$config = [
    'class' => 'yii\db\Connection',
    'dsn' => 'mysql:host=127.0.0.1;dbname=demo',
    'username' => 'root',
    'password' => '',
    'charset' => 'utf8',
];

$db = Yii::createObject($config);

Метод [[Yii::createObject()]] принимает в качестве аргумента массив с конфигурацией и создаёт объект указанного в них класса. При этом оставшаяся часть конфигурации используется для инициализации свойств, обработчиков событий и поведений объекта.

Если объект уже создан, вы можете использовать [[Yii::configure()]] для того, чтобы инициализировать свойства объекта массивом с конфигурацией:

Yii::configure($object, $config);

Обратите внимание, что в этом случае массив с конфигурацией не должен содержать ключ class.

Формат конфигурации

Формат конфигурации выглядит следующим образом:

[
    'class' => 'ClassName',
    'propertyName' => 'propertyValue',
    'on eventName' => $eventHandler,
    'as behaviorName' => $behaviorConfig,
]

где

• Элемент class указывает абсолютное имя класса создаваемого объекта.
• Элементы propertyName указывают первоначальные значения свойств создаваемого объекта. Ключи являются именами свойств создаваемого объекта, а значения — начальными значениями свойств создаваемого объекта. Таким способом могут быть установлены только публичные переменные объекта и его свойства, созданные через геттеры и сеттеры.
• Элементы on eventName указывают на то, какие обработчики должны быть прикреплены к событиям объекта. Обратите внимание, что ключи массива начинаются с on. Чтобы узнать весь список поддерживаемых видов обработчиков событий обратитесь в раздел события
• Элементы as behaviorName указывают на то, какие поведения должны быть внедрены в объект. Обратите внимание, что ключи массива начинаются с as; а $behaviorConfig представляет собой конфигурацию для создания поведения, похожую на все остальные конфигурации.

Пример конфигурации с установкой первоначальных значений свойств объекта, обработчика событий и поведения:

[
    'class' => 'app\components\SearchEngine',
    'apiKey' => 'xxxxxxxx',
    'on search' => function ($event) {
        Yii::info("Keyword searched: " . $event->keyword);
    },
    'as indexer' => [
        'class' => 'app\components\IndexerBehavior',
        // ... начальные значения свойств ...
    ],
]

Использование конфигурации

Конфигурации повсеместно используются в Yii. В самом начале данной главы мы узнали как создать объект с необходимыми параметрами используя метод [[Yii::createObject()]]. В данном разделе речь пойдет о конфигурации приложения и конфигурациях виджетов — двух основных способов использования конфигурации.

Конфигурация приложения

Конфигурация приложения, пожалуй, самая сложная из используемых в фреймворке. Причина в том, что класс [[yii\web\Application|application]] содержит большое количество конфигурируемых свойств и событий. Более того, свойство приложения [[yii\web\Application::components|components]] может принимать массив с конфигурацией для создания компонентов, регистрируемых на уровне приложения. Пример конфигурации приложения для шаблона приложения basic.

$config = [
    'id' => 'basic',
    'basePath' => dirname(__DIR__),
    'extensions' => require(__DIR__ . '/../vendor/yiisoft/extensions.php'),
    'components' => [
        'cache' => [
            'class' => 'yii\caching\FileCache',
        ],
        'mailer' => [
            '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',
        ],
    ],
];

Ключ class в данной конфигурации не указывается. Причина в том, что класс вызывается по полному имени во входном скрипте:

(new yii\web\Application($config))->run();

За более подробной документацией о настройках свойства components в конфигурации приложения обратитесь к главам приложения и Service Locator.

Конфигурации виджетов

При использовании виджетов часто возникает необходимость изменить параметры виджета с помощью конфигурации. Для создания виджета можно использовать два метода: [[yii\base\Widget::widget()]] и [[yii\base\Widget::begin()]]. Оба метода принимают конфигурацию в виде 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],
    ],
]);

Данный код создает виджет Menu и устанавливает параметр виджета activeItems в значение false. Также устанавливается параметр items, состоящий из элементов меню.

Обратите внимание что параметр class НЕ передается, так как полное имя уже указано.

Конфигурационные файлы

Если конфигурация очень сложная, то её, как правило, разделяют по нескольким PHP файлам. Такие файлы называют Конфигурационными файлами. Конфигурационный файл возвращает массив PHP являющийся конфигурацией. Например, конфигурацию приложения можно хранить в отдельном файле web.php, как показано ниже:

return [
    'id' => 'basic',
    'basePath' => dirname(__DIR__),
    'extensions' => require(__DIR__ . '/../vendor/yiisoft/extensions.php'),
    'components' => require(__DIR__ . '/components.php'),
];

Параметр components также имеет сложную конфигурацию, поэтому можно его хранить в файле components.php и подключать в файл web.php используя require как и показано выше. Содержимое файла components.php:

return [
    'cache' => [
        'class' => 'yii\caching\FileCache',
    ],
    'mailer' => [
        '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',
    ],
];

Чтобы получить конфигурацию, хранящуюся в файле, достаточно подключить файл с помощью require:

$config = require('path/to/web.php');
(new yii\web\Application($config))->run();

Значения конфигурации по умолчанию

Метод [[Yii::createObject()]] реализован с использованием dependency injection container. Это позволяет задавать так называемые значения конфигурации по умолчанию, которые будут применены ко ВСЕМ экземплярам классов во время их инициализации методом [[Yii::createObject()]]. Значения конфигурации по умолчанию указываются с помощью метода Yii::$container->set() на этапе предварительной загрузки.

Например, если мы хотим изменить виджет [[yii\widgets\LinkPager]] так, чтобы все виджеты данного вида показывали максимум 5 кнопок на странице вместо 10 (как это установлено изначально), можно использовать следующий код:

\Yii::$container->set('yii\widgets\LinkPager', [
    'maxButtonCount' => 5,
]);

Без использования значений конфигурации по умолчанию, при использовании LinkPager, вам пришлось бы каждый раз задавать значение maxButtonCount.

Константы окружения

Конфигурации могут различаться в зависимости от режима, в котором происходит запуск приложения. Например, в окружении разработчика (development) вы используете базу данных mydb_dev, а в эксплуатационном (production) окружении базу данных mydb_prod. Для упрощения смены окружений в Yii существует константа YII_ENV. Вы можете указать её во входном скрипте своего приложения:

defined('YII_ENV') or define('YII_ENV', 'dev');

YII_ENV может принимать следующие значения:

• prod: окружение production, т.е. эксплуатационный режим сервера. Константа YII_ENV_PROD установлена в true. Значение по умолчанию.
• dev: окружение development, т.е. режим для разработки. Константа YII_ENV_DEV установлена в true.
• test: окружение testing, т.е. режим для тестирования. Константа YII_ENV_TEST установлена в true.

Используя эти константы, вы можете задать в конфигурации значения параметров зависящие от текущего окружения. Например, чтобы включить отладочную панель и отладчик в режиме разработки, вы можете использовать следующий код в конфигурации приложения:

$config = [...];

if (YII_ENV_DEV) {
    // значения параметров конфигурации для окружения разработки 'dev'
    $config['bootstrap'][] = 'debug';
    $config['modules']['debug'] = 'yii\debug\Module';
}

return $config;