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

Вступ

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

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

Команда `about`

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

php artisan about

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

php artisan about --only=environment

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

php artisan config:show database

Конфігурація середовища

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

Щоб зробити це простим, Laravel використовує PHP-бібліотеку DotEnv. У щойно встановленому Laravel кореневий каталог застосунку містить файл .env.example, який визначає багато поширених змінних середовища. Під час встановлення Laravel цей файл автоматично копіюється в .env.

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

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

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

Безпека файлу середовища

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

Утім, файл середовища можна зашифрувати вбудованим шифруванням середовища Laravel. Зашифровані файли середовища можна безпечно додавати до контролю версій.

Додаткові файли середовища

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

Типи змінних середовища

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

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

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

APP_NAME="My Application"

Отримання конфігурації середовища

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

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

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

Визначення поточного середовища

Поточне середовище застосунку визначається змінною APP_ENV із вашого файлу .env. Отримати це значення можна методом environment фасаду App:

use Illuminate\Support\Facades\App;

$environment = App::environment();

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

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

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

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

Шифрування файлів середовища

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

Шифрування

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

php artisan env:encrypt

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

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

Довжина наданого ключа має відповідати довжині, якої потребує використовуваний шифр. За замовчуванням Laravel використовує шифр AES-256-CBC, який потребує ключа з 32 символів. Ви вільні використовувати будь-який шифр, що його підтримує шифрувальник Laravel, передавши опцію --cipher під час виклику команди.

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

php artisan env:encrypt --env=staging

Читабельні імена змінних

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

php artisan env:encrypt --readable

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

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

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

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

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

Розшифрування

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

php artisan env:decrypt

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

php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

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

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

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

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

php artisan env:decrypt --env=staging

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

php artisan env:decrypt --force

Доступ до значень конфігурації

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

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:

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

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

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

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

Кешування конфігурації

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

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

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

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

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

php artisan config:clear

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

Публікація конфігурації

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

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

php artisan config:publish

php artisan config:publish --all

Режим налагодження

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

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

Режим обслуговування

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

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

php artisan down

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

php artisan down --refresh=15

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

php artisan down --retry=60

Обхід режиму обслуговування

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

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

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

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

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

php artisan down --with-secret

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

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

Режим обслуговування на кількох серверах

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

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

APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=database

Попередній рендеринг представлення режиму обслуговування

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

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

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

Перенаправлення запитів у режимі обслуговування

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

php artisan down --redirect=/

Вимкнення режиму обслуговування

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

php artisan up

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

Режим обслуговування та черги

Поки ваш застосунок у режимі обслуговування, жодні завдання з черг не оброблятимуться. Обробка завдань відновиться як звичайно, щойно застосунок вийде з режиму обслуговування.

Альтернативи режиму обслуговування

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