Yii Knowledge Base

Quick reference for Yii3 framework patterns and PHP implementation guidelines. Yii3 is a complete rewrite — modular, PSR-compliant, and designed for modern PHP 8.4+ applications with clean architecture support.

Core Principles

PSR Compliance

Yii3 implements PSR-3 (log), PSR-4 (autoload), PSR-7/PSR-17 (HTTP messages/factories via

yiisoft/http-message

yiisoft/di

yiisoft/middleware-dispatcher

Middleware Pipeline

Request → [Router] → [Auth] → [CORS] → [Action] → Response
              ↓                            ↓
         yiisoft/router            Application Logic

Rule: All HTTP handling flows through the PSR-15 middleware pipeline. No global state.

Modular Package Architecture

Yii3 is split into independent packages (

yiisoft/*

Quick Checklists

DDD-Compatible Yii3 Project

• Domain layer has zero

  use Yiisoft\

  imports
• ActiveRecord used only in Infrastructure layer
• Repository interfaces defined in Domain layer
• Value Objects used instead of primitives in Domain
• Actions/Controllers only map input and delegate to UseCases
• DI container configured via providers, not service locator
• Domain events dispatched through domain

  EventDispatcherInterface

  port (not PSR-14 directly)
• RBAC Rules delegate business logic to domain Specifications
• Queue handlers delegate to Application UseCases
• Infrastructure components (Cache, HTTP Client) accessed via domain ports

Clean Architecture Checks

• No

  Yiisoft\ActiveRecord

  in Domain or Application layers
• No HTTP concerns (

  ServerRequestInterface

  ) in Application layer
• Middleware handles cross-cutting concerns (auth, CORS, logging)
• Config files separate from business logic
• Service providers wire interfaces to implementations
• Tests do not depend on Yii container for unit tests

Common Violations Quick Reference

use Yiisoft\ActiveRecord

$container->get()

use Yiisoft\

use Yiisoft\Auth

use Yiisoft\Rbac

QueueInterface

CacheInterface

Yii::$app->

PHP 8.4 Yii Patterns

Action (Single Action Controller)

declare(strict_types=1);

namespace Presentation\Api\Order;

final readonly class CreateOrderAction
{
    public function __construct(
        private CreateOrderUseCase $createOrder,
        private OrderRequestMapper $mapper,
    ) {}

    public function __invoke(ServerRequestInterface $request): ResponseInterface
    {
        $dto = $this->mapper->fromRequest($request);
        $result = $this->createOrder->execute($dto);

        return $this->responseFactory->createJson($result->toArray(), 201);
    }
}

PSR-15 Middleware

declare(strict_types=1);

namespace Infrastructure\Http\Middleware;

final readonly class CorrelationIdMiddleware implements MiddlewareInterface
{
    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler,
    ): ResponseInterface {
        $correlationId = $request->getHeaderLine('X-Correlation-ID') ?: Uuid::v4();
        $request = $request->withAttribute('correlationId', $correlationId);

        return $handler->handle($request)
            ->withHeader('X-Correlation-ID', $correlationId);
    }
}

UseCase with DI

declare(strict_types=1);

namespace Application\Order\UseCase;

final readonly class CreateOrderUseCase
{
    public function __construct(
        private OrderRepositoryInterface $orders,
        private EventDispatcherInterface $events,
    ) {}

    public function execute(CreateOrderDTO $dto): OrderResultDTO
    {
        $order = Order::create(
            id: $this->orders->nextIdentity(),
            customerId: $dto->customerId,
            lines: $dto->lines,
        );
        $this->orders->save($order);
        $this->events->dispatch(...$order->releaseEvents());

        return OrderResultDTO::fromEntity($order);
    }
}

References

For detailed information, load these reference files:

• references/architecture.md

  — Yii3 modular architecture, middleware pipeline, config system

• references/ddd-integration.md

  — Extracting Domain from Yii, Repository pattern, Domain Events

• references/routing-http.md

  — Routing, Actions, PSR-7/PSR-15 middleware

• references/persistence.md

  — ActiveRecord, Cycle ORM, migrations, Repository pattern

• references/dependency-injection.md

  — yiisoft/di container, service providers, PSR-11

• references/testing.md

  — PHPUnit, fixtures, functional testing, middleware testing

• references/security.md

  — RBAC, authentication, IdentityInterface adapter, password hashing, CSRF

• references/event-system.md

  — PSR-14 dispatcher, listeners, domain event bridge, stoppable events

• references/queue.md

  — yii-queue, messages, handlers, middleware pipelines, retry, channels

• references/infrastructure-components.md

  — Cache (PSR-16), Rate Limiter, HTTP Client (PSR-18), Mailer with DDD ports

• references/antipatterns.md

  — Yii2-in-Yii3 detection, framework coupling, fat controllers, RBAC in Domain, missing queue resilience