Установка Symfony и первый запуск: где спотыкаются новички

За 15–20 минут вы получите работающий проект Symfony, открытый в браузере по адресу https://127.0.0.1:8000. Статья про Symfony 7.x и PHP 8.2+ — именно эта пара сейчас актуальна. Ниже — рабочая последовательность команд и разбор ошибок, на которых чаще всего застревают те, кто ставит фреймворк впервые.

Что нужно иметь до старта

Symfony 7.x требует PHP 8.2 или новее. Если у вас PHP 8.1 — установщик проекта откажется работать, и никакие флаги это не обойдут. Проверьте до всего остального.

• PHP 8.2+ с расширениями ctype, iconv, mbstring, xml, tokenizer. Проверка: php -v и php -m.
• Composer 2.x — менеджер зависимостей PHP.¹ Проверка: composer --version.
• Symfony CLI — необязателен, но с ним запуск сервера и проверки удобнее. Ставится отдельно с symfony.com/download.
• Git — Composer тянет часть пакетов из репозиториев.

Отдельно проверьте требования окружения командой из Symfony CLI:

symfony check:requirements

Если строка заканчивается словами Your system is ready to run Symfony projects — можно продолжать. Красные строки покажут, чего именно не хватает.

Создание проекта

Есть два пути. Через Symfony CLI:

# Полноценное веб-приложение с Twig, роутингом и профайлером
symfony new my_project --webapp

# Минимальный «скелет» без лишнего — под API или микросервис
symfony new my_project

Или напрямую через Composer, без установленного CLI:

# Веб-приложение
composer create-project symfony/skeleton my_project
cd my_project
composer require webapp

Проверка: после успешной установки в каталоге my_project появятся папки src, config, public и файл composer.json. Если папки нет — установка не завершилась, читайте вывод команды до конца, а не только последнюю строку.

Разница между --webapp и обычным скелетом

Минимальный скелет — это несколько десятков строк конфигурации и пустой контроллер. Флаг --webapp (или пакет webapp) добавляет Twig, формы, Doctrine, валидатор, профайлер и maker-bundle. Новичку почти всегда нужен второй вариант: иначе на первом же уроке придётся вручную доставлять половину пакетов.

Запуск локального сервера

Перейдите в каталог проекта и поднимите сервер:

cd my_project
symfony server:start

В консоли появится строка вида [OK] Web server listening ... https://127.0.0.1:8000. Откройте этот адрес в браузере — увидите приветственную страницу Symfony с версией фреймворка и PHP.

Если Symfony CLI не установлен, поднять сервер можно средствами PHP:

php -S 127.0.0.1:8000 -t public/

Разница существенная: встроенный сервер PHP отдаёт только HTTP и не знает про TLS, а symfony server:start сразу поднимает HTTPS с локальным сертификатом и корректно работает с профайлером. Для учебных задач сгодится и php -S, но в туториалах обычно предполагается адрес именно от Symfony CLI.

Symfony не падает «просто так». В 90% случаев причина — версия PHP, отсутствующее расширение или права на каталог. Прочитайте вывод команды целиком: настоящая причина почти всегда в первых строках ошибки, а не в последней.

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

Ошибки, которые встречаются чаще всего, и что с ними делать.

1. Your requirements could not be resolved ... requires php >=8.2 — у вас PHP старше требуемого либо Composer видит не ту версию. Проверьте php -v. Если в системе несколько версий PHP, Composer мог взять не ту — запустите его явно нужным бинарником: php8.2 /usr/local/bin/composer create-project ....
2. the requested PHP extension mbstring is missing (или intl, xml) — не установлено расширение. На Debian/Ubuntu: sudo apt install php8.2-mbstring php8.2-xml php8.2-intl, затем перезапустите терминал и повторите установку.
3. Address already in use при server:start — порт 8000 занят другим процессом или уже запущенным сервером. Остановите старый: symfony server:stop, либо запустите на другом порту: symfony server:start --port=8001.
4. Страница отдаёт 500 и ничего понятного в браузере — включён prod-режим и ошибки скрыты. Убедитесь, что в файле .env стоит APP_ENV=dev. В dev-режиме Symfony показывает подробную страницу исключения с трейсом.
5. Unable to write in the cache directory или var/log — нет прав на запись. Отдайте каталогам var/cache и var/log права вашему пользователю. На Linux в учебной среде проще всего работать из-под своего пользователя, а не root, чтобы кеш не создавался с чужими правами.

Про composer вместо symfony new

Если вы не ставили Symfony CLI, все команды с symfony работать не будут — command not found. Это не поломка: используйте связку composer create-project для создания и php -S для запуска. CLI просто удобная надстройка, без неё Symfony тоже работает.

Куда смотреть после первого запуска

Проект поднялся — дальше стоит освоить три вещи, без которых не выйдет ни один туториал:

• maker-bundle: команда php bin/console make:controller создаёт контроллер за секунду. Доступна, если вы ставили с --webapp.
• Профайлер: нижняя панель на странице в dev-режиме показывает запросы, время, обращения к БД. Это ваш главный инструмент отладки.
• Файл .env: здесь окружение и строка подключения к базе. Секреты в prod хранят не тут, но для локальной разработки этого достаточно.

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

¹ Composer — менеджер зависимостей для PHP: скачивает библиотеки, указанные в composer.json, и следит за их совместимостью по версиям. Аналог npm в мире JavaScript.