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

Конфигурации широко используются в 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' => 'ClassName',
    'propertyName' => 'propertyValue',
    'on eventName' => $eventHandler,
    'as behaviorName' => $behaviorConfig,
]
  • Элемент class указывает полное имя класса для создаваемого объекта.
  • Элементы propertyName задают начальные значения для именованного свойства. Ключи - это имена свойств, а значения - соответствующие начальные значения. Могут быть настроены только общедоступные переменные-члены и свойства, определенные с помощью getters/seters.
  • Элементы on eventName указывают, какие обработчики должны быть привязаны к событиям объекта. Обратите внимание, что ключи массива формируются путем префиксации имен событий с помощью on
  • Элементы как 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. Это связано с тем, что класс приложения имеет множество настраиваемых свойств и событий. Более того, свойство его компонентов может получать массив конфигураций для создания компонентов, зарегистрированных в приложении. Ниже приведен фрагмент из файла конфигурации приложения для шаблона Basic Project.

$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();

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

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

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

При использовании виджетов часто нужно использовать конфигурации для настройки свойств виджета. Оба метода 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.php и «требуйте» этот файл в web.php, как показано выше. Содержимое component.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 в каждом месте, где вы используете пейджеры ссылок.

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

Конфигурации часто меняются в зависимости от среды, в которой выполняется приложение. Например, в среде разработки вы можете использовать базу данных с именем 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;