Русский
Español- Начало работы
- Конфигурация
Документация Laravel 10.x
Конфигурация
Присоединяйся к нашему Telegram сообществу @webblend!
Здесь ты найдешь сниппеты по Laravel и полезные советы по веб-разработке.
- Введение
- Настройка среды выполнения
- Доступ к значениям конфигурации
- Кэширование конфигурации
- Режим отладки
- Режим обслуживания
Введение
Все файлы конфигурации для фреймворка Laravel хранятся в каталоге config. Каждая опция документирована, поэтому не стесняйтесь просматривать файлы и ознакомьтесь с доступными вам опциями.
Эти файлы конфигурации позволяют настраивать такие вещи, как информация о подключении к базе данных, информация о почтовом сервере, а также различные другие основные значения конфигурации, такие как временная зона приложения и ключ шифрования.
Обзор приложения
В спешке? Вы можете быстро получить обзор конфигурации, драйверов и окружения вашего приложения с помощью команды Artisan about:
php artisan aboutЕсли вас интересует только определенный раздел вывода обзора приложения, вы можете отфильтровать этот раздел, используя опцию --only:
php artisan about --only=environmentИли, чтобы изучить подробные значения определенного файла конфигурации, вы можете использовать команду Artisan config:show:
php artisan config:show databaseНастройка среды выполнения
Часто бывает полезно иметь различные значения конфигурации в зависимости от окружения, в котором выполняется приложение. Например, вы можете захотеть использовать другой драйвер кэширования локально, чем на вашем сервере продакшена.
Для упрощения этого процесса Laravel использует библиотеку DotEnv для PHP. В новой установке Laravel корневой каталог вашего приложения содержит файл .env.example, в котором определено множество общих переменных среды. В процессе установки Laravel этот файл будет автоматически скопирован в .env.
В файле .env по умолчанию Laravel содержит некоторые общие значения конфигурации, которые могут отличаться в зависимости от того, выполняется ли ваше приложение локально или на веб-сервере продакшена. Эти значения затем извлекаются из различных файлов конфигурации Laravel в каталоге config с использованием функции Laravel env.
Если вы разрабатываете с командой, вы можете продолжать включать файл .env.example в вашем приложении. Помещая заполнители значений в файл конфигурации-примера, другие разработчики вашей команды смогут четко видеть, какие переменные среды им нужны для запуска вашего приложения.
Примечание Любую переменную в вашем файле
.envможно переопределить внешними переменными среды, такими как переменные среды на уровне сервера или системные переменные среды.
Безопасность файла окружения
Файл .env вашего приложения не следует добавлять в систему управления версиями, так как каждый разработчик / сервер, использующий ваше приложение, может потребовать различную конфигурацию окружения. Кроме того, это может представлять собой угрозу безопасности в случае, если злоумышленник получит доступ к вашему хранилищу управления версиями, поскольку могут быть раскрыты конфиденциальные учетные данные.
Однако вы можете зашифровать ваш файл окружения, используя встроенное в Laravel шифрование окружения. Зашифрованные файлы окружения можно безопасно размещать в системе управления версиями.
Дополнительные файлы окружения
Перед загрузкой переменных среды вашего приложения Laravel определяет, предоставлена ли внешняя переменная среды APP_ENV или указан аргумент CLI --env. Если это так, Laravel попытается загрузить файл .env.[APP_ENV], если он существует. Если его нет, будет загружен файл .env по умолчанию.
Типы переменных среды
Все переменные в ваших файлах .env обычно парсятся как строки, поэтому были созданы некоторые зарезервированные значения, чтобы позволить вам возвращать более широкий диапазон типов из функции env():
.env Value |
env() Value |
|---|---|
| true | (bool) true |
| (true) | (bool) true |
| false | (bool) false |
| (false) | (bool) false |
| 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, - это "значение по умолчанию". Это значение будет возвращено, если для заданного ключа не существует переменной среды.
Определение текущей среды выполнения
Текущую среду выполнения приложения определяет переменная 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'])) { // Среда выполнения — локальная или тестовая...}Примечание Текущую среду выполнения приложения можно переопределить, определив переменную среды
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:
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 из любого места вашего приложения. Значения конфигурации могут быть получены с использованием синтаксиса "точка", который включает в себя имя файла и опцию, которую вы хотите получить. Также можно указать значение по умолчанию, которое будет возвращено, если опции конфигурации не существует:
$value = config('app.timezone'); // Получение значения по умолчанию, если значение конфигурации не существует...$value = config('app.timezone', 'Asia/Seoul');Для установки значений конфигурации во время выполнения передайте массив функции config:
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Внимание Если вы выполняете команду
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 выдаст вашему браузеру файл 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. Например, вы можете захотеть перенаправить все запросы по адресу /:
php artisan down --redirect=/Отключение режима обслуживания
Чтобы отключить режим обслуживания, используйте команду up:
php artisan upПримечание Вы можете настроить шаблон режима обслуживания по умолчанию, определив свой собственный шаблон в
resources/views/errors/503.blade.php.
Режим обслуживания и очереди
В режиме обслуживания ваше приложение не будет обрабатывать очереди задач. Обработка задач будет продолжена как обычно после выхода приложения из режима обслуживания.
Альтернативы режиму обслуживания
Поскольку режим обслуживания требует отключения вашего приложения на несколько секунд, рассмотрите альтернативы, такие как Laravel Vapor и Envoyer, чтобы добиться развертывания Laravel без простоев.