concept-configurations.md 13.9 KB
Newer Older
1
Настройки
2
========
3 4 5 6

Настройки широко используются в Yii при создании новых объектов или при инициализации уже существующих объектов. 
Обычно настройки включают в себя названия классов создаваемых объектов и список первоначальных значений
которые должны быть присвоены [свойствам](concept-properties.md) объекта. Также в настройках можно указать список
7
[обработчиков событий](concept-events.md) объекта, и/или список [поведений](concept-behaviors.md) объекта.
8 9 10 11 12 13 14 15 16 17 18 19 20 21 22

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

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

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

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

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

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

33
Обратите внимание, что в этом случае массив с настройками не должен содержать ключ `class`.
34 35


36
## Формат настроек <a name="configuration-format"></a>
37 38 39 40 41 42 43 44 45 46 47 48 49 50

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

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

где

51
* Элемент `class` указывает абсолютное имя класса создаваемого объекта.
52
* Элементы `propertyName` указывают первоначальные значения свойств создаваемого объекта. Ключи являются именами свойств
53 54 55
  создаваемого объекта, а значения — начальными значениями свойств создаваемого объекта.
  Таким способом могут быть установлены только публичные переменные объекта и его [свойства](concept-properties.md),
  созданные через геттеры и сеттеры.
56 57 58 59 60 61 62
* Элементы `on eventName` указывают какие обработчики должны быть установлены для [событий](concept-events.md) объекта.
  Обратите внимание, что ключи массива начинаются с `on `. Чтобы узнать весь список поддерживаемых видов
  обработчиков событий обратитесь в раздел [события](concept-events.md)
* Элементы `as behaviorName` указывают какие [поведения](concept-behaviors.md) должны быть установлены для объекта.
  Обратите внимание, что ключи массива начинаются с `as `. `$behaviorConfig` это массив для настройки
  поведения, этот массив такой же как тот, о котором идет речь.

63
Пример настроек с установкой первоначальных значений свойств объекта, обработчика событий и поведения:
64 65 66 67 68 69 70 71 72 73

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


80
## Использование настроек <a name="using-configurations"></a>
81

82 83 84
Возможность настройки широко используется в Yii. В самом начале данной главы мы узнали как
создать объект с необходимыми параметрами используя метод [[Yii::createObject()]].
В данном разделе речь пойдет о настройках приложения и настройках виджетов — двух основных способов
85 86 87
использования настроек. 


88
### Настройки приложения <a name="application-configurations"></a>
89 90 91

Настройки [приложения](structure-applications.md) пожалуй самые сложные из используемых в фреймворке.
Причина в том, что класс [[yii\web\Application|application]] содержит большое количество настраиваемых
92 93 94
свойств и событий. Более того, свойство приложения [[yii\web\Application::components|components]]
может принимать массив настроек для создания компонентов, регистрируемых на уровне приложения.
Пример настроек приложения для [шаблона приложения basic](start-basic.md).
95 96 97 98 99 100 101 102 103 104

```php
$config = [
    'id' => 'basic',
    'basePath' => dirname(__DIR__),
    'extensions' => require(__DIR__ . '/../vendor/yiisoft/extensions.php'),
    'components' => [
        'cache' => [
            'class' => 'yii\caching\FileCache',
        ],
105
        'mailer' => [
106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128
            '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` в данных настройках не указывается. Причина в том, что класс вызывается по полному имени во
129
[входном скрипте](structure-entry-scripts.md):
130 131 132 133 134

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

135 136
Для более подробной документации о настройке свойства приложения `components` обратитесь к главам
[приложения](structure-applications.md) и [Service Locator](concept-service-locator.md).
137 138


139
### Настройки виджетов <a name="widget-configurations"></a>
140 141 142

При использовании [виджетов](structure-widgets.md) часто возникает необходимость изменить параметры виджета с помощью
настроек. Для создания виджета можно использовать два метода: [[yii\base\Widget::widget()]] и 
143
[[yii\base\Widget::beginWidget()]]. Оба метода принимают настройки в виде массива:
144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160

```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`, состоящий из элементов меню.

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


## Файлы Настроек <a name="configuration-files"></a>

166 167
Если настройки сложные, то их, как правило, разделяют по нескольким PHP файлам. Такие файлы называют
*файлами настроек* или *конфигурационными файлами*. Файл настроек возвращает массив PHP с настройками.
168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187
Например, настройки приложения можно хранить в отдельном файле `web.php`, как показано ниже:

```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`:

```php
return [
    'cache' => [
        'class' => 'yii\caching\FileCache',
    ],
188
    'mailer' => [
189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209
        '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',
    ],
];
```

210
Чтобы получить настройки, хранимые в файле, достаточно подключить файл с помощью `require`:
211 212 213 214 215 216 217 218 219 220

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


## Настройки по умолчанию <a name="default-configurations"></a>

Метод [[Yii::createObject()]] реализован с использованием [dependency injection container](concept-di-container.md).
221 222 223
Это позволяет указывать так называемые *настройки по умолчанию*, которые будут применены ко ВСЕМ экземплярам классов
во время их инициализации методом [[Yii::createObject()]]. Настройки по умолчанию указываются с помощью метода
`Yii::$container->set()` на этапе [предварительной загрузки](runtime-bootstrapping.md).
224

225 226
Например, если мы хотим изменить виджет [[yii\widgets\LinkPager]] так, чтобы все виджеты данного вида показывали максимум
5 кнопок на странице вместо 10 (как это установлено изначально), можно использовать следующий код:
227 228 229 230 231 232 233 234 235 236 237

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

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


238
## Константы окружения <a name="environment-constants"></a>
239 240

Настройки могут различаться в зависимости от окружения, в котором происходит запуск приложения. Например,
241
в окружении разработчика вы используете базу данных `mydb_dev`, а на продакшн сервере базу данных
242
`mydb_prod`. Для упрощения смены окружений в Yii существует константа `YII_ENV`.  Вы можете указать её во 
243
[входном скрипте](structure-entry-scripts.md) своего приложения:
244 245 246 247 248 249 250

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

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

251 252 253 254
- `prod`: production окружение, т.е. окружение для конечного сервера. Константа `YII_ENV_PROD` установлена в true.
   Значение по умолчанию.
- `dev`: development окружение, т.е. окружение для разработки. Константа `YII_ENV_DEV` установлена в true.
- `test`: testing окружение, т.е. окружения для тестирования. Константа `YII_ENV_TEST` установлена в true.
255

256
Используя эти константы вы можете изменить настройки в соответствии с вашим окружением.
257 258 259 260 261 262 263 264 265 266 267 268 269 270
Например, чтобы включить [отладочную панель и отладчик](tool-debugger.md) в development окружении вы можете использовать 
следующие настройки приложения: 

```php
$config = [...];

if (YII_ENV_DEV) {
    // настройки для 'dev' окружения
    $config['bootstrap'][] = 'debug';
    $config['modules']['debug'] = 'yii\debug\Module';
}

return $config;
```