Конфигурация в Laravel: короткая инструкция для старта

Через 15–20 минут у вас будет проект на Laravel с настроенным подключением к базе, отдельными значениями для локальной разработки и продакшена и пониманием, почему после правки .env сайт иногда «не видит» новые настройки. Всё показано на Laravel 11.x — на 10.x различия минимальны, отдельно отмечу, где они есть.

Работать будем с двумя вещами: файлом .env в корне проекта и папкой config/. Первый хранит значения, которые меняются от машины к машине (пароли, адреса, ключи). Вторая — PHP-файлы, которые эти значения читают и раздают приложению.

Что нужно иметь до начала

• установленный PHP 8.2 или выше (Laravel 11 требует минимум 8.2);
• Composer — для установки зависимостей;
• готовый проект: если его ещё нет, создайте командой composer create-project laravel/laravel my-app;
• доступ к терминалу в корне проекта — там, где лежат artisan и composer.json.

При установке через create-project файл .env и ключ приложения создаются автоматически. Если вы клонировали чужой репозиторий — этих файлов не будет, их создание разберём в первом шаге.

Пошаговая настройка

Шаг 1. Создайте .env из образца

В репозитории .env не хранят — вместо него лежит .env.example без секретов. Скопируйте его:

cp .env.example .env

На Windows в PowerShell: Copy-Item .env.example .env. После этого в корне проекта должен появиться файл .env. Откройте его — увидите строки вида APP_NAME=Laravel, каждая на своей строке, без пробелов вокруг знака =.

Шаг 2. Сгенерируйте ключ приложения

Ключ шифрует сессии и cookie. Без него Laravel будет падать с ошибкой. Выполните:

php artisan key:generate

Команда впишет значение в строку APP_KEY=. Проверка: откройте .env, строка APP_KEY должна содержать длинную последовательность после base64:, а не быть пустой.

Шаг 3. Задайте окружение и отладку

Две ключевые строки в начале файла:

APP_ENV=local
APP_DEBUG=true

На локальной машине оставьте так — при ошибке увидите подробную страницу с трейсом. На боевом сервере обязательно поставьте APP_ENV=production и APP_DEBUG=false, иначе посетители увидят содержимое переменных и путь к файлам. Это самая частая утечка на молодых проектах.

Шаг 4. Подключите базу данных

Найдите блок с префиксом DB_ и заполните под свою СУБД. Для MySQL:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=my_app
DB_USERNAME=root
DB_PASSWORD=YOUR_DB_PASSWORD

В Laravel 11 в новом проекте по умолчанию стоит DB_CONNECTION=sqlite — если вам нужен MySQL или PostgreSQL, поменяйте значение и раскомментируйте остальные строки блока. Проверка: выполните php artisan migrate. Если данные подключения верны, миграции создадут таблицы; при ошибке доступа команда сразу об этом скажет.

Шаг 5. Читайте значения в коде правильно

Прямой вызов env('DB_HOST') в контроллерах и сервисах — ошибка, которую совершают почти все новички. Функция env() перестаёт работать после кеширования конфигурации (об этом ниже) и в проде вернёт null. Правильный путь: значение из .env читает файл в config/, а код обращается к конфигу через config().

// В config/services.php добавляем свой блок:
return [
    // ...существующие сервисы
    'sms' => [
        // env() допустим ТОЛЬКО внутри файлов config/
        'key' => env('SMS_API_KEY'),
        'sender' => env('SMS_SENDER', 'MyApp'), // второй аргумент — значение по умолчанию
    ],
];

// А в контроллере или сервисе читаем уже через config():
$apiKey = config('services.sms.key');
$sender = config('services.sms.sender');

Правило простое: env() живёт только в папке config/, во всём остальном коде — config().

Если вы вызываете env() где-то за пределами config/, считайте, что на боевом сервере эта строка вернёт null. Кеш конфигурации отключит доступ к переменным окружения — и приложение сломается ровно там, где локально всё работало.

Шаг 6. Закешируйте конфигурацию на проде

На боевом сервере Laravel читает десятки PHP-файлов конфигурации при каждом запросе. Команда собирает их в один кеш-файл:

php artisan config:cache

После этого приложение работает быстрее, но перестаёт читать .env напрямую. Проверка: команда выведет Configuration cached successfully. Локально этот кеш обычно не включают — он мешает разработке.

Когда сбрасывать кеш

Главная боль после первого знакомства: правите .env, а сайт показывает старое значение. Причина — активный кеш конфигурации. Он не обновляется автоматически.

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

Если не получилось

• No application encryption key has been specified — не выполнен php artisan key:generate или строка APP_KEY пустая. Запустите генерацию ключа.
• SQLSTATE[HY000] [1045] Access denied for user — неверный DB_USERNAME или DB_PASSWORD. Проверьте данные и сбросьте кеш: php artisan config:clear.
• config() возвращает null — в вашем файле config/ нет нужного ключа либо опечатка в пути (services.sms.key). Точечная нотация должна совпадать со структурой массива.
• env() вернул null в проде, локально всё работало — вы вызываете env() вне папки config/. Перенесите чтение в конфиг-файл, в коде используйте config().
• Изменения .env не видны — активен кеш. Выполните php artisan config:clear и обновите страницу.

Что настроить дальше

Базовое окружение готово. Следующие шаги, когда упрётесь в них:

• отдельные значения для тестов — файл .env.testing, Laravel подхватывает его при запуске PHPUnit;
• публикация конфигов пакетов через php artisan vendor:publish, чтобы менять их настройки;
• хранение секретов вне .env на проде — переменные окружения самого сервера или менеджер секретов, тема отдельная.

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