Skip to content
Laravel
Icon

ПРЕДУПРЕЖДЕНИЕ Вы просматриваете документацию к старой версии Laravel. Рассмотрите возможность обновления Вашего проекта до Laravel 9.x.

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

Введение

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

These configuration files allow you to configure things like your database connection information, your mail server information, as well as various other core configuration values such as your application timezone and encryption key.

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

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

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

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

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

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

Безопасность файлов среды

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

Additional Environment Files

Before loading your application's environment variables, Laravel determines if either the APP_ENV environment variable has been externally provided or if the --env CLI argument has been specified. If so, Laravel will attempt to load an .env.[APP_ENV] file if it exists. If it does not exist, the default .env file will be loaded.

Типы переменных среды

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

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

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

APP_NAME="Мое приложение"

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

Все переменные, перечисленные в этом файле, будут загружены в суперглобал 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'])) {
    // Среда является локальной ИЛИ промежуточной...
}

{tip} Текущее обнаружение среды приложения может быть отменено путем определения переменной среды уровня сервера APP_ENV .

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

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

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

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

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

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

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

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

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

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

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

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

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

Когда ваше приложение находится в режиме обслуживания, для всех запросов к вашему приложению будет отображаться настраиваемое представление. Это позволяет легко «отключить» ваше приложение во время его обновления или во время обслуживания. Проверка режима обслуживания включена в стек мидлвара по умолчанию для вашего приложения. Если приложение находится в режиме обслуживания, экземпляр 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 выдаст Вашему браузеру файл куки обхода режима обслуживания:

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

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

{tip} Your maintenance mode secret should typically consist of alpha-numeric characters and, optionally, dashes. You should avoid using characters that have special meaning in URLs such as ?.

Предварительная визуализация представления режима обслуживания

Если Вы используете команду 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

{tip} Вы можете настроить шаблон режима обслуживания по умолчанию, определив свой собственный шаблон в resources/views/errors/503.blade.php.

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

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

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

Поскольку режим обслуживания требует, чтобы Ваше приложение простаивало несколько секунд, рассмотрите альтернативы, такие как Laravel Vapor и Envoyer, чтобы выполнить развертывание с нулевым временем простоя с Laravel.