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

• Вступ
• Конфігурація середовища
  • Типи Змінних Середовища
  • Отримання конфігурації середовища
  • Визначення поточного середовища
  • Шифрування файлів середовища
• Доступ до значень конфігурації
• Кешування Конфігурації
• Публікація конфігурації
• Режим налагодження
• Режим обслуговування

Вступ

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

These конфігураційні файли дозволяють налаштувати такі речі, як інформація про підключення до вашої бази даних, інформація про ваш поштовий сервер, а також різні інші основні конфігураційні значення, такі як 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 не повинен бути закомічений у систему контролю версій вашого застосунку, оскільки кожен розробник / сервер, що використовує ваш застосунок, може вимагати різної конфігурації середовища. Крім того, це буде ризиком для безпеки у випадку, якщо зловмисник отримає доступ до вашого репозиторію системи контролю версій, оскільки будь-які конфіденційні облікові дані будуть розкриті.

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

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

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

Типи Змінних Середовища

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

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

APP_NAME="My Application"

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

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

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

Другим значенням, переданим у функцію env, є "значення за замовчуванням". Це значення буде повернено, якщо для заданого ключа не існує змінної середовища.

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

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

use Illuminate\Support\Facades\App;
 
$environment = App::environment();

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

if (App::environment('local')) {
    // Середовище є локальним
}
 
if (App::environment(['local', 'staging'])) {
    // Середовище є або локальним, АБО проміжним...
}

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

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

Шифрування

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

php artisan env:encrypt

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

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

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

php artisan env:encrypt --env=staging

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

Щоб розшифрувати файл середовища, ви можете використовувати команду 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

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

php artisan env:decrypt --force

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

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

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

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

Більшість конфігураційних файлів 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.

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

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

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

php artisan down

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

php artisan down --refresh=15

Ви також можете надати опцію retry для команди down, яка буде встановлена як значення заголовка 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 буде видано вашому браузеру, ви зможете переглядати застосунок нормально, ніби він не знаходиться в режимі обслуговування.

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

За замовчуванням 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

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

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

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

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