Инструкция для разработчиков (Backend)

Этот документ описывает, как настроить окружение, запустить проект, писать код в соответствии с архитектурой проекта, добавлять модули, команды, события и тестировать изменения.

Стек технологий

ТехнологияВерсияНазначение
PHP8.1+Язык
Yii22.0.45+Фреймворк
MySQL8.0Основная БД
Redis7.0Кэш, push-уведомления
Passport—Внешний SSO-сервис (OAuth2)
Swagger-PHP5.8Генерация OpenAPI-документации
PHPStan2.2Статический анализ
PHP-CS-Fixer3.95Стиль кода
Codeception4/5Тесты
vlucas/phpdotenv5.6Переменные окружения

1. Локальный запуск

1.1. Требования

1.2. Установка

# 1. Клонировать репозиторий
git clone <url-репозитория> taskflow.api
cd taskflow.api

# 2. Установить зависимости
composer install

# 3. Создать .env из примера
cp .env.example .env
# Отредактировать .env: БД, Redis, MAILER, OAUTH2_*
#  - OAUTH2_PUBLIC_KEY_PATH — путь к публичному ключу Passport (RS256)
#  - OAUTH2_CLIENT_ID / OAUTH2_CLIENT_SECRET — регистрация клиента в Passport

# 4. Применить миграции
php yii migrate --interactive=0

# 5. Запустить dev-сервер
php yii serve --docroot=web

Приложение доступно на http://localhost:8080.

1.3. Docker / Vagrant

2. Переменные окружения (.env)

Все секреты и настройки окружения хранятся в .env (не в коде). Обязательные переменные — см. core/configuration.md.

Файл .env.example — эталон; .env — актуальные значения и он не должен попадать в git (см. .gitignore).

⚠️ Никогда не коммить .env с реальными секретами.

3. Команды консоли

Проект использует ./yii (Linux) / yii.bat (Windows).

php yii migrate                   # Применить миграции
php yii migrate --interactive=0   # Без подтверждения
php yii email-send                # Отправка писем (очередь; см. commands/EmailSendCommand.php)
php yii cache/flush-all           # Полный сброс кэша
php yii serve --docroot=web       # Dev-сервер

Полезные Composer-скрипты:

composer test                      # Все тесты
composer test:unit                 # Юнит-тесты
composer test:api                  # API-тесты
composer lint                      # Проверка стиля (dry-run)
composer lint-fix                  # Авто-исправление стиля
composer unclestan:6               # PHPStan level 6 по core/ и modules/

4. Архитектура: как писать код

4.1. Слои

Строго соблюдаем слои (подробно: core/architecture.md):

presentation/  →  application/  →  domain/
                        ↑               ↑
              infrastructure реализует порты (application/port/* и domain/repository/*)

4.2. CQRS-шаблон добавления новой операции

Пример добавления операции «создать что-то»:

  1. Command в application/command/ — CreateXxxCommand (immutable, поля через конструктор).
  2. Handler в application/handler/ — CreateXxxHandler с методом handle(CreateXxxCommand $command): XxxDto.
  3. Query (если чтение) в application/query/ — GetXxxQuery, хендлер GetXxxHandler.
  4. DTO в application/dto/ — выходной объект с полями, реализует \JsonSerializable при необходимости.
  5. Controller в presentation/controller/ — действие вызывает $this->container->get(Handler::class)->handle(...).
  6. Request-модель (валидация входных данных) — в presentation/request/.
  7. Зарегистрировать хендлер в DI (см. п. 4.3) и маршрут в config/routing.php модуля.

4.3. Регистрация зависимостей (DI)

// config/di.php модуля
Yii::$container->set(IXxxRepository::class, function () {
    return new DbXxxRepository(Yii::$app->db);
});
Yii::$container->set(CreateXxxHandler::class);

4.4. События и слушатели

Доменные события — основной способ реакции на изменения (уведомления, логирование, авто-действия).

  1. Создать событие в domain/event/ — класс с геттерами (immutable).
  2. В коде хендлера вызвать диспетчер: $this->eventDispatcher->dispatch(new XxxEvent(...)).
  3. Подписать слушателя:
    • локально в модуле — в config/di.php в ModuleEventDispatcher или DispatchingEventDecorator;
    • глобально (для событий других модулей/ядра) — $globalDispatcher->addListener(EventClass::class, Listener::class).

Примеры: core/events.md, modules/tasks, modules/projects.

4.5. Миграции

php yii migrate/create create_xxx_table --namespace=modules\\xxx\\infrastructure\\migrations

Именование: m260224_132707_create_tasks_table.php (год_месяц_день_время_суффикс).

4.6. Маршруты

5. Тестирование

5.1. Структура тестов

5.2. Запуск

composer test          # все
composer test:unit     # только юнит
composer test:api      # только API
vendor/bin/codecept run unit tests/unit/models/SomeTest      # конкретный тест

5.3. Качество кода

composer lint-fix          # php-cs-fixer
composer unclestan:6       # phpstan level=6

Конфигурация: .php-cs-fixer.dist.php, phpstan.neon + phpstan-bootstrap.php.

6. CI/CD

GitHub Actions: .github/workflows/ci_cd.yml

Деплой в продакшн — только через настроенные CI/CD пайплайны, вручную — запрещено.

7. Стандарты кода (кратко)

Подробно: specification/code-style.md.

8. Чек-лист добавления нового модуля

  1. Создать modules/<name>/ со слоями application|domain|infrastructure|presentation.
  2. Module.php — класс модуля.
  3. config/di.php — репозитории, хендлеры, слушатели.
  4. config/routing.php — маршруты.
  5. config/params.php — параметры модуля (если нужны).
  6. Зарегистрировать модуль в config/modules.php, подключить di.php и routing.php в config/web.php.
  7. Миграции в infrastructure/migrations/ + namespace в config/migration_namespaces.php.
  8. Swagger-аннотации на контроллерах (#[OA\Get], #[OA\Post] и т.д.).
  9. Тесты в tests/.
  10. Документация модуля в docs/modules/<name>/.