symfony-knowledge

name: symfony-knowledge description: Symfony framework knowledge base. Provides architecture, DDD integration, persistence, DI, security, messenger, workflow, events, infrastructure components, testing, and antipatterns for Symfony PHP projects.

Symfony Knowledge Base

Quick reference for Symfony framework patterns, DDD integration, and PHP implementation guidelines for auditing and generating Symfony-based applications.

Core Principles

• Bundle System — Symfony's plugin mechanism. Third-party code is installed as bundles; application code lives outside bundles in src/.
• Symfony Flex — Automates bundle installation via recipes. Standard dirs: config/, src/, public/, var/, migrations/, tests/, templates/.
• Kernel — Entry point that boots the container, registers bundles, loads configuration. Must remain thin — no business logic.

Quick Checklists

DDD-Compatible Symfony Project

• Domain layer has zero Symfony imports
• Doctrine mapping uses XML or PHP config (not entity attributes)
• Controllers are invokable (single action per class)
• Messenger handles commands and queries via separate buses
• Value Objects use custom Doctrine types
• Repository interfaces in Domain, implementations in Infrastructure
• services.yaml binds interfaces to implementations
• Domain events are dispatched, not Doctrine lifecycle events
• Authorization uses Voters delegating to domain Specifications
• Workflow guards delegate to domain Specifications (no inline business logic)
• Domain defines its own EventDispatcherInterface (not Symfony's)
• Infrastructure components (Cache, HTTP Client) accessed via domain ports

Clean Architecture in Symfony

• No use Symfony\ in Domain or Application layers
• No use Doctrine\ in Domain layer
• Use Cases accept Command/Query DTOs, not Request objects
• Controllers only map HTTP to Use Case calls
• EventSubscribers do not contain business logic
• Compiler passes do not encode domain rules

Common Violations Quick Reference

PHP 8.4 Symfony Patterns

Invokable Controller (Single Action)

<?php
declare(strict_types=1);
namespace App\Order\Presentation\Api;

use App\Order\Application\Command\CreateOrderCommand;
use App\Order\Application\UseCase\CreateOrderUseCase;
use Symfony\Component\HttpFoundation\{JsonResponse, Request, Response};
use Symfony\Component\Routing\Attribute\Route;

#[Route('/api/orders', methods: ['POST'])]
final readonly class CreateOrderAction
{
    public function __construct(private CreateOrderUseCase $createOrder) {}

    public function __invoke(Request $request): JsonResponse
    {
        $data = $request->toArray();
        $orderId = $this->createOrder->execute(new CreateOrderCommand(
            customerId: $data['customer_id'],
            items: $data['items'],
        ));

        return new JsonResponse(['id' => $orderId->value], Response::HTTP_CREATED);
    }
}

Use Case (Application Service)

<?php
declare(strict_types=1);
namespace App\Order\Application\UseCase;

use App\Order\Domain\Entity\Order;
use App\Order\Domain\Repository\OrderRepositoryInterface;
use App\Shared\Domain\EventDispatcherInterface;

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

    public function execute(CreateOrderCommand $command): OrderId
    {
        $order = Order::create($command->customerId, $command->items);
        $this->orders->save($order);

        foreach ($order->releaseEvents() as $event) {
            $this->events->dispatch($event);
        }

        return $order->id();
    }
}

Messenger Command Handler

<?php
declare(strict_types=1);
namespace App\Order\Application\Handler;

use App\Order\Application\Command\ConfirmOrderCommand;
use App\Order\Domain\Repository\OrderRepositoryInterface;
use Symfony\Component\Messenger\Attribute\AsMessageHandler;

#[AsMessageHandler(bus: 'command.bus')]
final readonly class ConfirmOrderHandler
{
    public function __construct(private OrderRepositoryInterface $orders) {}

    public function __invoke(ConfirmOrderCommand $command): void
    {
        $order = $this->orders->findById($command->orderId);
        $order->confirm();
        $this->orders->save($order);
    }
}

References

For detailed information, load these reference files:

• references/architecture.md — Bundle system, Flex recipes, standard vs DDD-aligned directory layout
• references/ddd-integration.md — Domain purity, Messenger CQRS, Domain Events, Value Objects with Doctrine
• references/routing-http.md — Invokable controllers, EventSubscribers, attribute routing, validation
• references/persistence.md — Doctrine ORM mapping, repositories, migrations, keeping Doctrine out of Domain
• references/dependency-injection.md — services.yaml, auto-wiring, tagged services, compiler passes, interface binding
• references/testing.md — WebTestCase, KernelTestCase, functional tests, fixtures, Messenger handler testing
• references/security.md — UserInterface adapter, Voters with Specifications, firewalls, password hashing, auth events
• references/messenger-advanced.md — Multiple buses, transports, retry strategy, DLQ, middleware, workers, serialization
• references/workflow.md — StateMachine for aggregates, enum places, guards with Specifications, audit trail
• references/event-system.md — EventDispatcher patterns, kernel events, domain event dispatching, PSR-14
• references/infrastructure-components.md — Cache, Lock, RateLimiter, HTTP Client, Serializer, Scheduler with DDD ports
• references/antipatterns.md — Fat controllers, entity as DTO, Doctrine in Domain, Service Locator, detection patterns