Конфигурирование

Введение

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

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

Команда about

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

php artisan about

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

php artisan about --only=environment

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

php artisan config:show database

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

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

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

Файл .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() для получения значений из переменных ваших конфигурационных файлов. Фактически, если вы просмотрите файлы конфигурации 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'])) {
    // Окружение либо локальное, либо промежуточное ...
}

Определение текущего окружения приложения может быть отменено путем определения переменной окружения 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:

Если ваше приложение имеет несколько файлов среды, например .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.

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

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

Для облегчения статического анализа фасад Config также предоставляет методы получения типизированной конфигурации. Если полученное значение конфигурации не соответствует ожидаемому типу, будет выдано исключение:

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

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

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

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

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

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

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

php artisan down

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

php artisan down --refresh=15

Вы также можете передать команде down параметр retry, значение которого будет установлено в заголовке Retry-After HTTP`, хотя браузеры обычно игнорируют этот заголовок:

php artisan down --retry=60

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

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

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

После перевода приложения в режим обслуживания, вы можете перейти по URL-адресу приложения, с учетом этого токена, и Laravel выдаст вашему браузеру файл куки для обхода режима обслуживания:

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

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

php artisan down --with-secret

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

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

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

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

Альтернативно, Laravel предлагает метод на основе кеша для работы в режиме обслуживания. Этот метод требует запуска команды php artisan down только на одном сервере. Чтобы использовать этот подход, измените настройку “driver” в файле config/app.php вашего приложения на cache. Затем выберите хранилище кэша, доступное для всех ваших серверов. Это гарантирует, что статус режима обслуживания постоянно поддерживается на каждом сервере:

'maintenance' => [
    'driver' => 'cache',
    '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 Vapor и Envoyer для выполнения развертывания с нулевым временем простоя.