Настройки

Настройки широко используются в 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',
        // ... property init values ...
    ],
]

Использование настроек

Настройки используются во многих местах в Yii. В начале этого раздела мы показали, как создать объект по заданным настройкам с помощью Yii::createObject(). В этом подразделе мы опишем настройки приложения и виджетов — два основных способа использования настроек.

Настройки приложения

Настройки приложения — один из самых сложных массивов в Yii. Это связано с тем, что класс приложения имеет множество настраиваемых свойств и событий. Более важно, что его свойство components может принимать массив настроек для создания компонентов, которые регистрируются через приложение. Следующее — фрагмент из файла настроек приложения для Шаблона базового проекта.

$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 приложения см. в разделе Приложения и разделе Локатор сервисов.

Начиная с версии 2.0.11, настройки приложения поддерживают конфигурацию Контейнера внедрения зависимостей с использованием свойства container. Например:

$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
        ]
    ]
];

Чтобы узнать больше о возможных значениях массивов настроек definitions и singletons и примерах из реальной жизни, пожалуйста, прочитайте подраздeл Практическое применение статьи Контейнер внедрения зависимостей.

Настройки виджетов

При работе с виджетами вам часто нужно использовать настройки для настройки свойств виджета. Для создания виджета можно использовать оба метода yii\base\Widget::widget() и yii\base\Widget::begin(). Они принимают массив настроек, как в следующем примере,

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 и инициализирует его свойство activateItems значением 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 как показано выше. Содержимое 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',
    ],
];

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

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

Настройки по умолчанию

Метод Yii::createObject() реализован на основе контейнера внедрения зависимостей. Он позволяет указать набор так называемых настроек по умолчанию, которые будут применяться ко ВСЕМ экземплярам указанных классов при их создании с помощью Yii::createObject(). Настройки по умолчанию можно указать, вызвав Yii::$container->set() в коде инициализации.

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

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

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

Константы среды

Настройки часто различаются в зависимости от среды, в которой работает приложение. Например, в среде разработки вы можете использовать базу данных с именем mydb_dev, а в рабочей среде — базу данных mydb_prod. Для облегчения переключения между средами Yii предоставляет константу с именем YII_ENV, которую вы можете определить в скрипте входа своего приложения. Например,

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

Вы можете определить YII_ENV как одно из следующих значений:

• prod: рабочая среда. Константа YII_ENV_PROD будет равна true. Это значение по умолчанию для YII_ENV, если вы его не определите.
• dev: среда разработки. Константа YII_ENV_DEV будет равна true.
• test: тестовая среда. Константа YII_ENV_TEST будет равна true.

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

$config = [...];

if (YII_ENV_DEV) {
    // configuration adjustments for 'dev' environment
    $config['bootstrap'][] = 'debug';
    $config['modules']['debug'] = 'yii\debug\Module';
}

return $config;