Джерело: https://laravelukraine.com/docs/13.x/configuration

# Конфігурація

- [Вступ](#introduction)
- [Конфігурація середовища](#environment-configuration)
    - [Типи змінних середовища](#environment-variable-types)
    - [Отримання конфігурації середовища](#retrieving-environment-configuration)
    - [Визначення поточного середовища](#determining-the-current-environment)
    - [Шифрування файлів середовища](#encrypting-environment-files)
- [Доступ до значень конфігурації](#accessing-configuration-values)
- [Кешування конфігурації](#configuration-caching)
- [Публікація конфігурації](#configuration-publishing)
- [Режим налагодження](#debug-mode)
- [Режим обслуговування](#maintenance-mode)

<a name="introduction"></a>
## Вступ

Усі конфігураційні файли фреймворку Laravel зберігаються в каталозі `config`. Кожна опція задокументована, тож не соромтеся переглянути файли та ознайомитися з доступними вам налаштуваннями.

Ці конфігураційні файли дозволяють налаштувати такі речі, як дані підключення до бази даних, дані поштового сервера, а також різні інші базові значення конфігурації - як-от URL застосунку та ключ шифрування.

<a name="the-about-command"></a>
#### Команда `about`

Laravel може показати огляд конфігурації, драйверів і середовища вашого застосунку за допомогою команди Artisan `about`.

```shell
php artisan about
```

Якщо вас цікавить лише певний розділ цього огляду, ви можете відфільтрувати його опцією `--only`:

```shell
php artisan about --only=environment
```

Або, щоб докладно дослідити значення конкретного конфігураційного файлу, скористайтеся командою Artisan `config:show`:

```shell
php artisan config:show database
```

<a name="environment-configuration"></a>
## Конфігурація середовища

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

Щоб зробити це простим, Laravel використовує PHP-бібліотеку [DotEnv](https://github.com/vlucas/phpdotenv). У щойно встановленому Laravel кореневий каталог застосунку містить файл `.env.example`, який визначає багато поширених змінних середовища. Під час встановлення Laravel цей файл автоматично копіюється в `.env`.

Типовий файл `.env` Laravel містить деякі поширені значення конфігурації, які можуть відрізнятися залежно від того, чи працює ваш застосунок локально, чи на робочому веб-сервері. Далі ці значення зчитуються конфігураційними файлами в каталозі `config` за допомогою функції Laravel `env`.

Якщо ви розробляєте в команді, варто й далі тримати у проєкті файл `.env.example` та оновлювати його. Розмістивши в цьому прикладі конфігурації значення-заповнювачі, ви дасте іншим розробникам вашої команди чітко побачити, які змінні середовища потрібні для запуску застосунку.

> [!NOTE]
> Будь-яку змінну у вашому файлі `.env` можуть перевизначити зовнішні змінні середовища - наприклад, задані на рівні сервера чи системи.

<a name="environment-file-security"></a>
#### Безпека файлу середовища

Ваш файл `.env` не слід додавати до системи контролю версій, оскільки кожен розробник чи сервер, що використовує ваш застосунок, може потребувати іншої конфігурації середовища. Ба більше, це створило б загрозу безпеці, якби зловмисник отримав доступ до вашого репозиторію, адже всі конфіденційні облікові дані опинилися б на видноті.

Утім, файл середовища можна зашифрувати вбудованим [шифруванням середовища](#encrypting-environment-files) Laravel. Зашифровані файли середовища можна безпечно додавати до контролю версій.

<a name="additional-environment-files"></a>
#### Додаткові файли середовища

Перш ніж завантажити змінні середовища вашого застосунку, Laravel визначає, чи задано ззовні змінну середовища `APP_ENV`, чи вказано аргумент CLI `--env`. Якщо так, Laravel спробує завантажити файл `.env.[APP_ENV]`, якщо той існує. Якщо ні - буде завантажено типовий файл `.env`.

<a name="environment-variable-types"></a>
### Типи змінних середовища

Усі змінні у ваших файлах `.env` зазвичай розбираються як рядки, тому було створено кілька зарезервованих значень, щоб функція `env()` могла повертати ширший діапазон типів:

<div class="overflow-auto">

| Значення в `.env` | Значення `env()` |
| ----------------- | ---------------- |
| true              | (bool) true      |
| (true)            | (bool) true      |
| false             | (bool) false     |
| (false)           | (bool) false     |
| empty             | (string) ''      |
| (empty)           | (string) ''      |
| null              | (null) null      |
| (null)            | (null) null      |

</div>

Якщо вам потрібно визначити змінну середовища зі значенням, що містить пробіли, візьміть це значення в подвійні лапки:

```ini
APP_NAME="My Application"
```

<a name="retrieving-environment-configuration"></a>
### Отримання конфігурації середовища

Усі змінні, перелічені у файлі `.env`, завантажуються в суперглобальний масив PHP `$_ENV`, коли ваш застосунок отримує запит. Однак у конфігураційних файлах для отримання значень цих змінних ви можете скористатися функцією `env`. Насправді, якщо переглянути конфігураційні файли Laravel, ви помітите, що багато опцій уже використовують цю функцію:

```php
'debug' => (bool) env('APP_DEBUG', false),
```

Друге значення, передане функції `env`, - це «значення за замовчуванням». Воно повернеться, якщо для вказаного ключа змінної середовища не існує.

<a name="determining-the-current-environment"></a>
### Визначення поточного середовища

Поточне середовище застосунку визначається змінною `APP_ENV` із вашого файлу `.env`. Отримати це значення можна методом `environment` [фасаду](/docs/{{version}}/facades) `App`:

```php
use Illuminate\Support\Facades\App;

$environment = App::environment();
```

Ви також можете передати методу `environment` аргументи, щоб перевірити, чи відповідає середовище певному значенню. Метод поверне `true`, якщо середовище збігається з будь-яким із переданих значень:

```php
if (App::environment('local')) {
    // The environment is local
}

if (App::environment(['local', 'staging'])) {
    // The environment is either local OR staging...
}
```

> [!NOTE]
> Визначення поточного середовища застосунку можна перевизначити, задавши змінну середовища `APP_ENV` на рівні сервера.

<a name="encrypting-environment-files"></a>
### Шифрування файлів середовища

Незашифровані файли середовища ніколи не слід зберігати в контролі версій. Однак Laravel дозволяє зашифрувати їх, щоб їх можна було безпечно додати до контролю версій разом із рештою застосунку.

<a name="encryption"></a>
#### Шифрування

Щоб зашифрувати файл середовища, скористайтеся командою `env:encrypt`:

```shell
php artisan env:encrypt
```

Виконання команди `env:encrypt` зашифрує ваш файл `.env` і помістить зашифрований вміст у файл `.env.encrypted`. Ключ розшифрування виводиться у результаті виконання команди, і його слід зберігати в надійному менеджері паролів. Якщо ви хочете надати власний ключ шифрування, скористайтеся опцією `--key` під час виклику команди:

```shell
php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF
```

> [!NOTE]
> Довжина наданого ключа має відповідати довжині, якої потребує використовуваний шифр. За замовчуванням Laravel використовує шифр `AES-256-CBC`, який потребує ключа з 32 символів. Ви вільні використовувати будь-який шифр, що його підтримує [шифрувальник](/docs/{{version}}/encryption) Laravel, передавши опцію `--cipher` під час виклику команди.

Якщо ваш застосунок має кілька файлів середовища, як-от `.env` і `.env.staging`, ви можете вказати файл, який слід зашифрувати, передавши ім'я середовища через опцію `--env`:

```shell
php artisan env:encrypt --env=staging
```

<a name="readable-variable-names"></a>
#### Читабельні імена змінних

Шифруючи файл середовища, ви можете скористатися опцією `--readable`, щоб зберегти видимими імена змінних, зашифрувавши лише їхні значення:

```shell
php artisan env:encrypt --readable
```

Це створить зашифрований файл такого формату:

```ini
APP_NAME=eyJpdiI6...
APP_ENV=eyJpdiI6...
APP_KEY=eyJpdiI6...
APP_DEBUG=eyJpdiI6...
APP_URL=eyJpdiI6...
```

Читабельний формат дозволяє бачити, які змінні середовища існують, не розкриваючи конфіденційних даних. Він також значно спрощує перегляд змін у pull request, адже ви бачите, які змінні було додано, вилучено чи перейменовано, не розшифровуючи файл.

Розшифровуючи файли середовища, Laravel автоматично визначає використаний формат, тож для команди `env:decrypt` жодних додаткових опцій не потрібно.

> [!NOTE]
> Коли використовується опція `--readable`, коментарі та порожні рядки з вихідного файлу середовища не потрапляють до зашифрованого результату.

<a name="decryption"></a>
#### Розшифрування

Щоб розшифрувати файл середовища, скористайтеся командою `env:decrypt`. Ця команда потребує ключа розшифрування, який Laravel візьме зі змінної середовища `LARAVEL_ENV_ENCRYPTION_KEY`:

```shell
php artisan env:decrypt
```

Або ж ключ можна передати команді напряму через опцію `--key`:

```shell
php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF
```

Коли викликано команду `env:decrypt`, Laravel розшифрує вміст файлу `.env.encrypted` і помістить розшифрований вміст у файл `.env`.

Команді `env:decrypt` можна передати опцію `--cipher`, щоб використати власний шифр:

```shell
php artisan env:decrypt --key=qUWuNRdfuImXcKxZ --cipher=AES-128-CBC
```

Якщо ваш застосунок має кілька файлів середовища, як-от `.env` і `.env.staging`, ви можете вказати файл, який слід розшифрувати, передавши ім'я середовища через опцію `--env`:

```shell
php artisan env:decrypt --env=staging
```

Щоб перезаписати наявний файл середовища, передайте команді `env:decrypt` опцію `--force`:

```shell
php artisan env:decrypt --force
```

<a name="accessing-configuration-values"></a>
## Доступ до значень конфігурації

Ви можете легко отримати значення конфігурації за допомогою фасаду `Config` або глобальної функції `config` із будь-якого місця вашого застосунку. Доступ до значень конфігурації здійснюється «крапковим» синтаксисом, що містить ім'я файлу та потрібної опції. Можна також вказати значення за замовчуванням, яке повернеться, якщо опції конфігурації не існує:

```php
use Illuminate\Support\Facades\Config;

$value = Config::get('app.timezone');

$value = config('app.timezone');

// Retrieve a default value if the configuration value does not exist...
$value = config('app.timezone', 'Asia/Seoul');
```

Щоб задати значення конфігурації під час виконання, викличте метод `set` фасаду `Config` або передайте масив функції `config`:

```php
Config::set('app.timezone', 'America/Chicago');

config(['app.timezone' => 'America/Chicago']);
```

Щоб полегшити статичний аналіз, фасад `Config` також надає типізовані методи отримання конфігурації. Якщо отримане значення не відповідає очікуваному типу, буде викинуто виняток:

```php
Config::string('config-key');
Config::integer('config-key');
Config::float('config-key');
Config::boolean('config-key');
Config::array('config-key');
Config::collection('config-key');
```

<a name="configuration-caching"></a>
## Кешування конфігурації

Щоб пришвидшити ваш застосунок, слід закешувати всі конфігураційні файли в один файл командою Artisan `config:cache`. Вона об'єднає всі опції конфігурації вашого застосунку в єдиний файл, який фреймворк зможе швидко завантажити.

Зазвичай команду `php artisan config:cache` варто виконувати як частину процесу розгортання в продакшені. Її не слід виконувати під час локальної розробки, оскільки опції конфігурації доведеться часто змінювати в процесі роботи над застосунком.

Щойно конфігурацію закешовано, фреймворк не завантажуватиме файл `.env` вашого застосунку під час запитів чи команд Artisan; отже, функція `env` повертатиме лише зовнішні змінні середовища системного рівня.

Тому переконайтеся, що викликаєте функцію `env` лише всередині конфігураційних (`config`) файлів вашого застосунку. Багато прикладів цього можна побачити в типових конфігураційних файлах Laravel. Доступ до значень конфігурації з будь-якого місця застосунку можна отримати функцією `config`, [описаною вище](#accessing-configuration-values).

Команда `config:clear` дозволяє очистити закешовану конфігурацію:

```shell
php artisan config:clear
```

> [!WARNING]
> Якщо ви виконуєте команду `config:cache` під час розгортання, переконайтеся, що викликаєте функцію `env` лише всередині конфігураційних файлів. Щойно конфігурацію закешовано, файл `.env` не завантажуватиметься; отже, функція `env` повертатиме лише зовнішні змінні середовища системного рівня.

<a name="configuration-publishing"></a>
## Публікація конфігурації

Більшість конфігураційних файлів Laravel уже опубліковано в каталозі `config` вашого застосунку; однак деякі файли, як-от `cors.php` і `view.php`, за замовчуванням не публікуються, адже більшості застосунків ніколи не знадобиться їх змінювати.

Утім, ви можете скористатися командою Artisan `config:publish`, щоб опублікувати будь-які конфігураційні файли, які не публікуються за замовчуванням:

```shell
php artisan config:publish

php artisan config:publish --all
```

<a name="debug-mode"></a>
## Режим налагодження

Опція `debug` у вашому конфігураційному файлі `config/app.php` визначає, скільки інформації про помилку насправді показується користувачеві. За замовчуванням ця опція налаштована на значення змінної середовища `APP_DEBUG`, яка зберігається у вашому файлі `.env`.

> [!WARNING]
> Для локальної розробки змінній середовища `APP_DEBUG` варто задати значення `true`. **У продакшен-середовищі це значення завжди має бути `false`. Якщо в продакшені змінна матиме значення `true`, ви ризикуєте розкрити конфіденційні значення конфігурації кінцевим користувачам вашого застосунку.**

<a name="maintenance-mode"></a>
## Режим обслуговування

Коли ваш застосунок перебуває в режимі обслуговування, для всіх запитів до нього показуватиметься спеціальне представлення. Це дозволяє легко «вимкнути» застосунок під час оновлення чи технічних робіт. Перевірка режиму обслуговування входить до типового стека `middleware` вашого застосунку. Якщо застосунок у режимі обслуговування, буде викинуто екземпляр `Symfony\Component\HttpKernel\Exception\HttpException` зі статус-кодом 503.

Щоб увімкнути режим обслуговування, виконайте команду Artisan `down`:

```shell
php artisan down
```

Якщо ви хочете, щоб з усіма відповідями в режимі обслуговування надсилався HTTP-заголовок `Refresh`, передайте опцію `refresh` під час виклику команди `down`. Заголовок `Refresh` вкаже браузеру автоматично оновити сторінку через задану кількість секунд:

```shell
php artisan down --refresh=15
```

Команді `down` можна також передати опцію `retry`, значення якої буде встановлено як HTTP-заголовок `Retry-After`, хоча браузери зазвичай його ігнорують:

```shell
php artisan down --retry=60
```

<a name="bypassing-maintenance-mode"></a>
#### Обхід режиму обслуговування

Щоб дозволити обхід режиму обслуговування за секретним токеном, скористайтеся опцією `secret` і вкажіть токен обходу:

```shell
php artisan down --secret="1630542a-246b-4b66-afa1-dd72a4c43515"
```

Перевівши застосунок у режим обслуговування, ви можете перейти за URL застосунку, що відповідає цьому токену, і Laravel видасть вашому браузеру cookie обходу режиму обслуговування:

```shell
https://example.com/1630542a-246b-4b66-afa1-dd72a4c43515
```

Якщо ви хочете, щоб Laravel згенерував секретний токен за вас, скористайтеся опцією `with-secret`. Секрет буде показано вам, щойно застосунок перейде в режим обслуговування:

```shell
php artisan down --with-secret
```

Звернувшись до цього прихованого маршруту, ви будете перенаправлені на маршрут `/` застосунку. Щойно cookie видано вашому браузеру, ви зможете переглядати застосунок як звичайно, ніби він і не в режимі обслуговування.

> [!NOTE]
> Ваш секрет режиму обслуговування зазвичай має складатися з літер і цифр та, за бажанням, дефісів. Уникайте символів, що мають спеціальне значення в URL, як-от `?` чи `&`.

<a name="maintenance-mode-on-multiple-servers"></a>
#### Режим обслуговування на кількох серверах

За замовчуванням Laravel визначає, чи перебуває застосунок у режимі обслуговування, за допомогою файлової системи. Це означає, що для активації режиму обслуговування команду `php artisan down` доведеться виконати на кожному сервері, де розміщено ваш застосунок.

Як альтернативу Laravel пропонує спосіб обробки режиму обслуговування на основі кешу. Цей спосіб потребує виконання команди `php artisan down` лише на одному сервері. Щоб скористатися ним, змініть змінні режиму обслуговування у файлі `.env` вашого застосунку. Оберіть сховище кешу (`store`), доступне всім вашим серверам. Це гарантує, що стан режиму обслуговування узгоджено підтримуватиметься на кожному сервері:

```ini
APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=database
```

<a name="pre-rendering-the-maintenance-mode-view"></a>
#### Попередній рендеринг представлення режиму обслуговування

Якщо ви використовуєте команду `php artisan down` під час розгортання, ваші користувачі все одно можуть іноді натрапляти на помилки, звертаючись до застосунку в момент, коли оновлюються залежності Composer чи інші компоненти інфраструктури. Це стається тому, що для визначення, що застосунок у режимі обслуговування, і рендерингу відповідного представлення шаблонізатором має завантажитися значна частина фреймворку Laravel.

Тому Laravel дозволяє попередньо відрендерити представлення режиму обслуговування, яке повертатиметься на самому початку циклу запиту. Це представлення рендериться до завантаження будь-яких залежностей вашого застосунку. Попередньо відрендерити потрібний шаблон можна опцією `render` команди `down`:

```shell
php artisan down --render="errors::503"
```

<a name="redirecting-maintenance-mode-requests"></a>
#### Перенаправлення запитів у режимі обслуговування

У режимі обслуговування Laravel показуватиме відповідне представлення для всіх URL застосунку, до яких намагається звернутися користувач. За бажанням ви можете вказати Laravel перенаправляти всі запити на конкретний URL. Це робиться опцією `redirect`. Наприклад, ви можете захотіти перенаправляти всі запити на URI `/`:

```shell
php artisan down --redirect=/
```

<a name="disabling-maintenance-mode"></a>
#### Вимкнення режиму обслуговування

Щоб вимкнути режим обслуговування, скористайтеся командою `up`:

```shell
php artisan up
```

> [!NOTE]
> Ви можете налаштувати типовий шаблон режиму обслуговування, визначивши власний у файлі `resources/views/errors/503.blade.php`.

<a name="maintenance-mode-queues"></a>
#### Режим обслуговування та черги

Поки ваш застосунок у режимі обслуговування, жодні [завдання з черг](/docs/{{version}}/queues) не оброблятимуться. Обробка завдань відновиться як звичайно, щойно застосунок вийде з режиму обслуговування.

<a name="alternatives-to-maintenance-mode"></a>
#### Альтернативи режиму обслуговування

Оскільки режим обслуговування потребує кількох секунд простою вашого застосунку, розгляньте можливість запускати застосунки на повністю керованій платформі на кшталт [Laravel Cloud](https://cloud.laravel.com), щоб досягти розгортання без простою.