Настройка

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

#Введение

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

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

#Обзор приложения

Спешите? Вы можете быстро получить обзор конфигурации вашего приложения, драйверов и окружения с помощью 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.

Если вы работаете в команде, рекомендуется продолжать включать файл .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 facade:

use Illuminate\Support\Facades\App;

$environment = App::environment();

Вы также можете передать аргументы методу environment, чтобы проверить, совпадает ли окружение с заданным значением. Метод вернёт true, если окружение совпадает с любым из переданных значений:

if (App::environment('local')) {
    // Окружение — локальное
}

if (App::environment(['local', 'staging'])) {
    // Окружение либо локальное, либо 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 из любой части вашего приложения. Значения конфигурации доступны через синтаксис с точками, который включает имя файла и нужный параметр. Также можно указать значение по умолчанию, которое будет возвращено, если параметр конфигурации отсутствует:

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

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

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

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

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

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

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

php artisan config:clear

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

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

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

Когда приложение находится в режиме обслуживания, для всех запросов будет отображаться специальное представление. Это позволяет «отключить» приложение во время обновления или обслуживания. Проверка режима обслуживания включена в стандартный стек middleware вашего приложения. Если приложение в режиме обслуживания, будет выброшено исключение Symfony\Component\HttpKernel\Exception\HttpException со статусом 503.

Чтобы включить режим обслуживания, выполните Artisan-команду down:

php artisan down

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

php artisan down --refresh=15

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

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

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