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

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

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

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

Начиная с версии 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' => [
                // Конфигурация для единожды создающихся объектов
            ]
        ]
    ];

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

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

При использовании виджетов часто возникает необходимость изменить параметры виджета с помощью конфигурации. Для создания виджета можно использовать два метода: 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() реализован с использованием контейнера внедрения зависимостей. Это позволяет задавать так называемые значения конфигурации по умолчанию, которые будут применены ко ВСЕМ экземплярам классов во время их инициализации методом 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;