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

Усі конфігураційні файли фреймворку 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 за допомогою функції env Laravel.

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

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

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

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

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

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

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

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

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

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

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')) {
    // Середовище — local
}

if (App::environment(['local', 'staging'])) {
    // Середовище — або local, АБО 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.

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

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');

// Отримати типове значення, якщо конфігураційне значення не існує...
$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, ви ризикуєте розкрити чутливі конфігураційні значення кінцевим користувачам вашого застосунку.

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

Коли ваш застосунок перебуває в режимі обслуговування, для всіх запитів до вашого застосунку відображатиметься спеціальне представлення (view). Це дозволяє легко «вимкнути» ваш застосунок, поки він оновлюється або поки ви виконуєте обслуговування. Перевірка режиму обслуговування включена до типового стеку 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.

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

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

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

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