Установка Lumen начинается не с самого фреймворка, а с проверки окружения: без установленного PHP нужной версии и менеджера зависимостей Composer команда создания проекта завершится ошибкой ещё на этапе загрузки пакетов. Поэтому первое действие — открыть терминал и убедиться, что оба инструмента доступны и корректно прописаны в системных путях.
Lumen — это облегчённый микрофреймворк от создателей Laravel, предназначенный для быстрых API и микросервисов. Он распространяется не установщиком, а через Composer, поэтому весь процесс сводится к нескольким командам в терминале. Ниже разберём каждый шаг: от подготовки системы до первого запуска встроенного сервера.
Проверка системных требований
Перед установкой убедитесь, что в системе присутствует PHP. Откройте командную строку (в Windows — cmd или PowerShell, в Linux и macOS — терминал) и выполните:
php -vЕсли команда возвращает версию PHP — интерпретатор установлен и доступен глобально. Если система отвечает, что команда не найдена, PHP нужно установить или добавить путь к нему в переменную окружения PATH. Точную минимальную версию PHP для актуального релиза Lumen стоит сверить с официальной документацией фреймворка — требования меняются от версии к версии.
Дополнительно проверьте наличие необходимых расширений PHP. Как правило, для работы потребуются OpenSSL, PDO и Mbstring. Посмотреть список подключённых модулей можно командой:
php -m⚠️ Внимание: если расширение присутствует в сборке PHP, но не активировано, оно не появится в выводеphp -m. Включить его можно, раскомментировав соответствующую строку в файлеphp.iniи перезапустив терминал.
Установка Composer
Composer — обязательный инструмент, без него поставить Lumen штатным способом не получится. Проверить его наличие просто:
composer --versionЕсли Composer не установлен, загрузите установщик с официального сайта проекта. На Windows доступен графический инсталлятор Composer-Setup.exe, который сам прописывает пути. На Linux и macOS установка выполняется через терминал согласно инструкции на сайте Composer — обычно это загрузка установочного скрипта и его запуск через PHP.
После установки закройте и заново откройте терминал, чтобы система подхватила обновлённые переменные окружения. Затем повторите проверку версии — это исключит ситуацию, когда Composer установлен, но терминал о нём «не знает».
Создание проекта Lumen
Когда PHP и Composer на месте, переходите в каталог, где должен располагаться проект, и выполните команду создания:
composer create-project --prefer-dist laravel/lumen имя-проектаВместо имя-проекта укажите название папки — Composer создаст её и загрузит туда весь код фреймворка вместе с зависимостями. Процесс может занять несколько минут в зависимости от скорости соединения: скачивается не только сам Lumen, но и десятки связанных пакетов.
Альтернативный вариант — глобальный установщик Lumen installer, который ставится через Composer и позволяет создавать проекты короткой командой lumen new. Он удобен, если вы планируете регулярно разворачивать новые проекты, но для разовой установки достаточно базовой команды create-project.
Пошаговая инструкция от нуля до запуска
Соберём весь процесс в единую последовательность. Этот порядок действий подходит для чистой системы, где ничего ещё не установлено.
☑️ Чек-лист установки Lumen
Каждый пункт чек-листа — самостоятельный этап, и пропуск любого из них приведёт к ошибке на следующем. Например, без файла .env приложение может не стартовать корректно, а без указания каталога public сервер вернёт ошибку 404 на любой запрос.
Настройка файла окружения .env
В корне свежего проекта лежит шаблон .env.example. Его нужно скопировать под именем .env — именно из этого файла Lumen читает конфигурацию: параметры приложения, подключения к базе данных, настройки кеша и очередей.
cp .env.example .envНа Windows в командной строке вместо cp используйте copy .env.example .env. После копирования откройте файл в редакторе и задайте ключ приложения APP_KEY — случайную строку длиной 32 символа. Она используется для шифрования данных, и оставлять её пустой в рабочем проекте нельзя.
⚠️ Внимание: файл.envсодержит пароли и ключи, поэтому его ни в коем случае не добавляют в систему контроля версий. В свежем проекте он уже внесён в.gitignore— проверьте, что эта строка на месте, прежде чем делать первый коммит.
Если проект будет работать с базой данных, в этом же файле укажите параметры подключения: драйвер, хост, порт, имя базы, логин и пароль. По умолчанию в Lumen многие компоненты, включая фасады и Eloquent, закомментированы в файле bootstrap/app.php — раскомментируйте соответствующие строки, иначе обращение к базе вызовет ошибку, хотя настройки в .env будут верными.
Зачем в Lumen отключены фасады и Eloquent по умолчанию
Разработчики фреймворка стремятся к максимальной скорости работы. Каждый подключённый компонент увеличивает время обработки запроса, поэтому «лишнее» выключено. Для простого API, не использующего базу данных, Eloquent можно не включать вовсе — приложение будет работать быстрее.
Запуск встроенного сервера и проверка
Для локальной разработки отдельный веб-сервер не нужен — достаточно встроенного сервера PHP. Из корня проекта выполните:
php -S localhost:8000 -t publicКлюч -t public указывает корневую директорию — именно там находится входная точка index.php. После запуска откройте в браузере адрес http://localhost:8000. Если всё настроено верно, вы увидите ответ приложения — обычно строку с версией Lumen.
Что проверить, если страница не открывается:
- 🔧 Порт 8000 не занят другим процессом — попробуйте другой порт, например
localhost:8080; - 📁 Команда запускалась из корня проекта, а не из другого каталога;
- 📄 Файл
.envсуществует и содержитAPP_KEY; - 🧩 В
bootstrap/app.phpраскомментированы нужные компоненты; - 📝 Подробности ошибки смотрите в логах в каталоге
storage/logs.
Сравнение способов запуска проекта
Встроенный сервер PHP подходит только для разработки. Для более серьёзных сценариев используются полноценные веб-серверы. Сравним варианты:
| Способ | Когда применять | Сложность настройки |
|---|---|---|
| Встроенный сервер PHP | Локальная разработка и отладка | Минимальная — одна команда |
| Apache с mod_php | Классический shared-хостинг | Средняя — нужен виртуальный хост |
| Nginx + PHP-FPM | Продакшен с высокой нагрузкой | Выше средней — отдельная настройка обоих сервисов |
| Docker-контейнер | Командная разработка, одинаковое окружение | Зависит от готовности конфигурации |
Для первого знакомства с фреймворком однозначно начинайте со встроенного сервера. Переходить к Nginx или контейнерам имеет смысл, когда проект уже работает локально и вы понимаете его структуру.
Типичные ошибки при установке
Самая частая проблема — ошибка Composer о несовместимости версий. Она означает, что установленная версия PHP не удовлетворяет требованиям пакетов. Решение одно: обновить PHP до подходящей версии, сверившись с требованиями в документации Lumen.
Вторая по распространённости ситуация — пустая страница или ошибка 500 сразу после установки. В этом случае первым делом откройте последний файл в storage/logs: там почти всегда записана конкретная причина, будь то отсутствующий .env, неверные права на каталоги storage и bootstrap/cache или отключённое расширение PHP.
Отдельно стоит упомянуть права доступа на Linux и macOS: веб-серверу и CLI нужна возможность записи в каталоги кеша и логов. Но не выставляйте права 777 на весь проект — это небезопасно. Достаточно дать права на запись только указанным папкам.
Часто задаваемые вопросы
Можно ли установить Lumen без Composer?
Технически можно вручную собрать все зависимости, но на практике это бессмысленно: у фреймворка десятки связанных пакетов со строгими требованиями к версиям. Composer разрешает эти зависимости автоматически, поэтому ручной способ не используют.
Чем Lumen отличается от Laravel и что выбрать?
Lumen — урезанная версия Laravel, оптимизированная под скорость: микросервисы и API без шаблонов, сессий и лишних компонентов. Если нужен полноценный сайт с админкой и страницами, берите Laravel. Если лёгкий API — Lumen.
Где хранятся настройки подключения к базе данных?
В файле .env в корне проекта: там задаются драйвер, хост, имя базы, логин и пароль. Дополнительно нужно раскомментировать строку с Eloquent в bootstrap/app.php, иначе работа с базой будет недоступна.
Почему браузер показывает ошибку 404 на всех страницах?
Чаще всего сервер запущен без указания каталога public — входная точка приложения находится именно там. Запустите сервер с ключом -t public из корня проекта. Если используется Apache или Nginx, проверьте, что корень виртуального хоста указывает на public.
Нужно ли ставить расширения PHP вручную?
Да, если они отсутствуют. Lumen требует несколько стандартных расширений — OpenSSL, PDO, Mbstring. В большинстве сборок они есть, но могут быть отключены в php.ini. Проверяйте вывод php -m и активируйте недостающие модули.