Установка Yii2 и структура проекта: разбор для новичка

К концу этой инструкции у вас будет работающий проект Yii2 на локальной машине: браузер откроет стартовую страницу с надписью «Congratulations!», а вы будете понимать, за что отвечает каждая папка в корне проекта. На чистой машине с уже установленным PHP и Composer это займёт минут 20–30. Разбираем актуальную линейку Yii 2.0.x (на момент написания — 2.0.49+) и basic-шаблон: именно с него стоит начинать, а не с advanced.

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

Если хотя бы один пункт не выполнен, установка упрётся в ошибку не на первом, а на третьем-четвёртом шаге — и вы потеряете время на диагностику не там, где проблема.

• PHP 7.4 или новее (Yii 2.0.x работает и на PHP 8.1–8.3). Проверьте: php -v в терминале должен вывести версию.
• Composer — менеджер зависимостей PHP. Проверьте: composer --version.
• Расширения PHP: pdo, mbstring, openssl, ctype. Обычно включены по умолчанию, но на минимальной сборке их может не быть.
• СУБД — не обязательна для первого запуска. Стартовая страница поднимется и без базы.

Composer ^* — инструмент, который скачивает библиотеки (пакеты) и их зависимости по описанию в файле composer.json. Для Yii2 это не опция, а обязательный способ установки: копировать фреймворк «архивом» с сайта давно не рекомендуют.

Шаг 1. Создаём проект

Откройте терминал в папке, где хотите держать проекты, и выполните одну команду. Она скачает шаблон и все зависимости:

composer create-project --prefer-dist yiisoft/yii2-app-basic myapp

Здесь myapp — имя папки проекта, поменяйте на своё. Composer спросит про плагин статистики — можно ответить y или n, на работу не влияет.

Проверка: в текущей директории появилась папка myapp, а внутри — файлы composer.json, requirements.php и папки controllers, views, web. Если Composer завис на «Loading composer repositories» — проблема с сетью или прокси, а не с Yii.

Шаг 2. Запускаем встроенный сервер

Для первого знакомства не нужен ни Apache, ни Nginx. У PHP есть встроенный веб-сервер, а у Yii — обёртка над ним:

cd myapp
php yii serve

По умолчанию поднимется на http://localhost:8080. Если порт занят, укажите свой: php yii serve --port=8888.

Проверка: откройте http://localhost:8080 в браузере. Должна появиться страница с большим заголовком «Congratulations!» и меню сверху. Если видите её — фреймворк работает.

Шаг 3. Проверяем требования окружения

Прежде чем настраивать реальный сервер, стоит убедиться, что PHP собран правильно. В корне проекта откройте в браузере requirements.php через тот же php yii serve, либо запустите из консоли:

php requirements.php

Скрипт выведет список проверок с пометками passed, warning и failed. На failed обращайте внимание в первую очередь: без нужного расширения приложение упадёт на первом же запросе к базе или сессии.

Структура проекта: что где лежит

Новичок открывает папку и видит десяток директорий с непонятными именами. Разберём те, куда вы будете лазить чаще всего, и те, куда лазить не нужно.

Главное правило безопасности Yii2: корнем сайта на боевом сервере должна быть папка web, а не корень проекта. Иначе конфиги с паролями от базы и папка runtime с логами окажутся доступны по прямой ссылке.

Как запрос проходит через проект

Понимание маршрута экономит часы на отладке. Запрос к /site/about идёт так: браузер → web/index.php → приложение читает config/web.php → находит SiteController в папке controllers → вызывает метод actionAbout() → тот рендерит шаблон views/site/about.php. Если страница не открывается — ищите обрыв именно в этой цепочке.

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

Пять ошибок, на которые новички тратят больше всего времени. Приводим текст, который вы реально увидите, и что с ним делать.

1. Белый экран, в логе «The directory is not writable by the Web process». Причина — нет прав на запись в runtime/ и web/assets/. Выдайте права: chmod -R 777 runtime web/assets для локальной разработки (на проде права настраивают строже, через владельца процесса).
2. «Class "yii\web\Application" not found» или ошибки автозагрузки. Не установлены зависимости или удалена папка vendor. Выполните composer install в корне проекта.
3. «Invalid Configuration – An invalid or expired request». Пустой или не заданный cookieValidationKey в config/web.php, блок request. При установке через create-project ключ подставляется автоматически; если вы копировали проект вручную — впишите любую длинную случайную строку.
4. «SQLSTATE... Connection refused» при обращении к базе. Не запущена СУБД или неверные данные в config/db.php. Для первого запуска страницы база вообще не нужна — ошибка вылезает, только когда вы обращаетесь к моделям с данными.
5. Страница открывается, но без стилей. Не сработала публикация ассетов из-за прав на web/assets/ (см. пункт 1) либо вы открываете проект не через web/. Проверьте, что корень указывает на папку web.

basic или advanced: не начинайте со второго

У Yii2 два официальных шаблона. Basic — одно приложение, плоская структура, всё, что описано выше. Advanced — разделение на frontend, backend и console с общим ядром common, отдельная процедура инициализации через php init. Для первого проекта берите basic: в advanced та же логика размазана по трём папкам, и на этапе, когда вы ещё ищете, где лежит контроллер, это только путает.

Что делать дальше

Когда стартовая страница открылась, следующие шаги такие: подключите базу в config/db.php, создайте первую таблицу и сгенерируйте для неё модель и CRUD через Gii — встроенный генератор кода (доступен по адресу /gii в режиме разработки). Дальше стоит прочитать раздел официального руководства про маршрутизацию и контроллеры: без него любой туториал будет казаться набором магии. Для боевого запуска отдельно изучите настройку веб-сервера так, чтобы корнем был web/, и переключите приложение из режима dev, убрав отладочную панель.