Конфигурация Laravel 10.x

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

Введение

Все конфигурационные файлы php-фреймворка Laravel хранятся в каталоге config. Каждая настройка документирована, поэтому смело просматривайте файлы и знакомьтесь с доступными вариантами настроек.

Эти конфигурационные файлы позволяют настроить такие параметры, как информация о подключении к базе данных, информация о почтовом сервере, а также другие основные параметры конфигурации, такие как часовой пояс приложения и ключ шифрования.

Обзор применения

Нужно сделать быстро? С помощью команды about Artisan можно получить быстрый обзор конфигурации, драйверов и окружения приложения:

php artisan about

Если требуется получить только определенный раздел обзора приложения, можно отфильтровать его с помощью параметра --only:

php artisan about --only=environment

Для детального изучения значений конкретного конфигурационного файла можно воспользоваться командой config:show Artisan:

php artisan config:show database

Конфигурация среды окружения

Часто бывает полезно иметь различные значения конфигурации в зависимости от среды, в которой работает приложение. Например, на локальном сервере может использоваться иной драйвер кэша, чем на рабочем сервере.

Чтобы упростить эту задачу, в Laravel используется PHP-библиотека DotEnv. При новой установке Laravel в корневом каталоге приложения будет находиться файл .env.example, определяющий множество общих переменных окружения. В процессе установки Laravel этот файл будет автоматически скопирован в .env.

Стандартный файл Laravel .env содержит некоторые общие значения конфигурации, которые могут отличаться в зависимости от того, работает ли ваше приложение локально или на рабочем веб-сервере. Эти значения затем извлекаются из различных конфигурационных файлов Laravel в каталоге config с помощью функции Laravel env.

Если разработка ведется в команде, то можно продолжить включать в приложение файл .env.example. Поместив в файл конфигурации example значения-заполнители, другие разработчики в команде разработчиков смогут наглядно увидеть, какие переменные окружения необходимы для работы данного приложения.

Любая переменная в файле .env может быть переопределена внешними переменными окружения, например, переменными окружения уровня сервера или системы.

Защита файлов среды окружения

Файл .env не следует передавать в систему управления исходным кодом приложения, поскольку для каждого разработчика и/или сервера, использующего данное приложение, может потребоваться своя конфигурация среды. Кроме того, в случае получения злоумышленником доступа к хранилищу исходных текстов это будет представлять угрозу безопасности, поскольку будут раскрыты все конфиденциальные учетные данные.

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

Дополнительные файлы среды окружения

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

Типы переменных среды окружения

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

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

Если необходимо задать переменную окружения со значением, содержащим пробелы, то можно заключить значение в двойные кавычки:

APP_NAME="My Application"

Получение конфигурации среды окружения

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

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

Второе значение, передаваемое функции env, - это "значение по умолчанию". Это значение будет возвращено, если для данного ключа не существует переменной окружения.

Определение текущего окружения

Текущее окружение приложения Laravel определяется через переменную 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 может быть переопределено путем определения переменной окружения APP_ENV на уровне сервера.

Шифрование файлов среды окружения

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

Шифрование

Для шифрования файла окружения 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.

Если в приложении Laravel имеется несколько файлов окружения, например .env и .env.staging, то можно указать файл окружения, который должен быть зашифрован, указав его имя с помощью параметра --env:

php artisan env:encrypt --env=staging

Дешифрование

Для расшифровки файла окружения Laravel используется команда 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

Если в приложении Laravel имеется несколько файлов окружения, например .env и .env.staging, то можно указать файл окружения, который должен быть расшифрован, задав имя окружения с помощью параметра --env:

php artisan env:decrypt --env=staging

Для того чтобы перезаписать существующий файл окружения, в команде env:decrypt предусмотрен параметр --force:

php artisan env:decrypt --force

Доступ к значениям конфигурации

При помощи глобальной функции config можно легко получить доступ к значениям конфигурации из любой точки приложения Laravel. Для доступа к значениям конфигурации используется синтаксис ., включающий имя файла и параметр, к которому необходимо получить доступ. Можно также указать значение по умолчанию, которое будет возвращено, если такой параметр не существует:

$value = config('app.timezone');
 
// Получение значения по умолчанию, если значение конфигурации не существует...
$value = config('app.timezone', 'Asia/Seoul');

Чтобы задать значения конфигурации во время выполнения программы, передайте массив в функцию config:

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

Кэширование конфигурации

Чтобы повысить скорость работы приложения Laravel, следует кэшировать все конфигурационные файлы в один файл с помощью команды Artisan config:cache. Это позволит объединить все параметры конфигурации приложения в один файл, который будет быстро загружаться фреймворком.

Обычно команду php artisan config:cache следует выполнять в процессе развертывания на рабочем сервере. Не следует выполнять эту команду во время локальной разработки, поскольку в процессе разработки приложения параметры конфигурации часто приходится изменять.

После кэширования конфигурации файл .env приложения Laravel не будет загружаться фреймворком при выполнении запросов или команд Artisan, поэтому функция env будет возвращать только внешние переменные окружения системного уровня.

По этой причине следует убедиться, что функция env вызывается только из конфигурационных файлов приложения (config). Многие примеры этого можно увидеть, изучив стандартные конфигурационные файлы Laravel. Доступ к значениям конфигурации можно получить из любой точки приложения с помощью функции config, описанной выше.

Для сброса закэшированной конфигурации может быть использована команда config:clear:

php artisan config:clear

Если команда config:cache выполняется в процессе развертывания, необходимо убедиться, что функция env вызывается только из конфигурационных файлов. После кэширования конфигурации файл .env не будет загружен, поэтому функция env будет возвращать только внешние переменные окружения системного уровня.

Режим отладки

Параметр debug в конфигурационном файле config/app.php определяет, какой объем информации об ошибке будет отображаться пользователю. По умолчанию этот параметр устанавливается с учетом значения переменной окружения APP_DEBUG, которая хранится в файле .env.

Для локальной разработки следует установить переменную окружения APP_DEBUG в значение true. В рабочей среде это значение всегда должно быть false. Если в рабочей среде переменная будет иметь значение true, вы рискуете открыть конечным пользователям приложения Laravel конфиденциальные значения его конфигурации.

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

Когда приложение Laravel находится в режиме обслуживания, для всех запросов к нему будет отображаться специальное представление. Это позволяет легко "отключить" приложение на время его обновления или выполнения технического обслуживания. Проверка режима обслуживания включена в стек 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

При обращении к этому секретному маршруту происходит перенаправление на маршрут / приложения. После того как cookie будет передан браузеру, можно будет просматривать приложение в обычном режиме, как если бы оно не находилось в режиме обслуживания.

Токен режима обслуживания обычно состоит из буквенно-цифровых символов и, по желанию, тире. Следует избегать использования символов, имеющих специальное значение в URL, таких как ? или &.

Предварительный рендеринг вида режима технического обслуживания

Если при выполнении внедрения использовать команду 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 Vapor и Envoyer, чтобы реализовать развертывание с нулевым временем простоя на Laravel.

Перевод с английского официальной документации Laravel 10.x:
https://laravel.com/docs/10.x/configuration

Заберите ссылку на статью к себе, чтобы потом легко её найти!
Раз уж досюда дочитали, то может может есть желание рассказать об этом месте своим друзьям, знакомым и просто мимо проходящим?
Не надо себя сдерживать! ;)