Symfony 7 clean architecture — Ops Runbook — Practical Guide (Oct 13, 2025)

Symfony 7 Clean Architecture — Ops Runbook

Level: Experienced

Date: 13 October 2025 | Symfony 7.0+ (stable)

Introduction

Symfony 7, released as a stable major version with backward compatibility considerations, presents an excellent foundation for implementing clean architecture principles in PHP applications. Clean architecture encourages separation of concerns, maintainability, and testability—qualities paramount in complex, long-lived systems. This ops runbook guides you through practical steps to structure, deploy, and operate Symfony 7 projects adhering to clean architecture conventions.

This article assumes you have practical experience with PHP, Symfony (versions 5 or later), and general architectural patterns like Hexagonal, Onion, or Clean Architecture. For teams evaluating architectural options, this runbook highlights pragmatic recommendations and touches on alternatives where relevant.

Prerequisites

Symfony 7.0+ installed and configured (stable release).
PHP 8.2+ (Symfony 7’s requirement).
Composer 2.6 or later for dependency management.
Familiarity with PSR-4 autoloading, Dependency Injection, and Symfony Bundle system.
Basic knowledge of Domain-Driven Design (DDD) concepts and testing frameworks like PHPUnit and Symfony’s test tools.
Configured CI/CD pipeline supporting automated testing and deployments.
Monitoring and logging tools (e.g., Symfony/Messenger + Monolog + Sentry) established in ops environment.

Hands-on Steps

1. Define Layered Project Structure

A clean architecture implementation in Symfony mandates distinct layers:

Domain Layer: Core business logic, entities, value objects. No dependencies on Symfony or infrastructure libraries.
Application Layer: Use cases / services – orchestrate domain operations, interface adapters.
Infrastructure Layer: Symfony bundles, database, external APIs, messaging.
Presentation Layer: Controllers, HTTP, API endpoints, CLI commands.

Recommended directory layout inside src/:


// Directory overview
src/
├── Domain/
│   ├── Model/
│   └── RepositoryInterface.php
├── Application/
│   ├── Service/
│   └── UseCase/
├── Infrastructure/
│   ├── Persistence/
│   ├── Messenger/
│   ├── SymfonyBundle/
├── UI/
│   ├── Controller/
│   ├── Command/
│   └── Form/

2. Use Dependency Inversion and Service Contracts

Define interfaces in the Domain or Application layer and implement them in Infrastructure. Bind interfaces to implementations explicitly in services.yaml or programmatically.


# config/services.yaml
services:
  AppDomainRepositoryUserRepositoryInterface: '@AppInfrastructurePersistenceUserRepository'

This inversion prevents domain code from depending on concrete Symfony or Doctrine implementations.

3. Integrate Doctrine ORM Thoughtfully

Doctrine remains the default persistence engine. Keep Doctrine entities in the Infrastructure/Persistence folder, distinct from domain entities.

Map Doctrine entities to domain objects explicitly via factories or mappers, avoiding pollution of domain with database annotations.


// Example mapper from Doctrine entity to domain entity
class UserMapper
{
    public static function toDomain(UserEntity $entity): User
    {
        return new User($entity->getId(), $entity->getName());
    }
}

4. Embrace Symfony Messenger for CQRS/Async Processing

Symfony 7 improves Messenger, which fits well to handle commands, queries, and events separately, enabling clear separation of concerns.

Organise messages and handlers under ApplicationMessage and InfrastructureMessenger, respectively.


// Example command
final class RegisterUserCommand
{
    public function __construct(public readonly string $email) {}
}

// Handler in Infrastructure
class RegisterUserHandler
{
    public function __construct(private UserRepositoryInterface $userRepo) {}

    public function __invoke(RegisterUserCommand $command)
    {
        // Business logic here
    }
}

5. Autowiring and Autoconfiguration Best Practices

Enable autowire: true and autoconfigure: true broadly, but explicitly tag handlers or domain services where needed.

Avoid service location anti-pattern by injecting dependencies explicitly in constructors.

6. Testing Aligned with Layers

Write isolated unit tests for domain entities and application services. Use functional tests for controllers and integration tests for infrastructure.

Leverage Symfony’s PHPUnit bridge and testing bundles for environment management.

Common Pitfalls

Mixing Domain and Infrastructure: Avoid placing Doctrine annotations or Symfony-specific code in domain objects.
Overusing Symfony Bundles: Keeping your application modular is good, but don’t introduce needless bundles for domain logic.
Ignoring Dependency Inversion: Directly coupling domain code to infrastructure classes undermines testability.
Excessive Code Generation: Symfony Flex recipes and code generators help, but generated code may need refactoring to fit clean architecture.
Messenger Configuration Complexity: Misconfigured transports or message buses can cause silent failures; monitor rigorously.

Validation

Confirm correctness and operational stability via:

Unit tests covering domain and application logic pass consistently.
Functional tests validate controller-level integrations.
Doctrine migrations execute without impacting domain model integrity.
Message handling queues process reliably under load.
Monitoring tools (e.g., Symfony profiler, Sentry) surfaced no critical errors in production.

Ensure code adheres to PSR standards and Symfony best practices with automated static analysis tools (PHPStan, Psalm).

Checklist / TL;DR

Project Structure: Separate Domain, Application, Infrastructure, UI folders.
Interfaces: Define contracts in Domain/Application, implement in Infrastructure.
Doctrine Entities: Keep persistence representations outside Domain layer.
Symfony Messenger: Use for commands/events, maintain message/handler separation.
Services: Use dependency injection, prefer constructor injection.
Testing: Write unit, functional, and integration tests per layer.
Monitoring: Set up logging and error tracking in production.

When to Choose Clean Architecture vs Alternatives

Clean architecture offers maximal decoupling but at added complexity and initial effort—best when long-term maintainability is critical.

For smaller or prototype projects, simpler architectures like traditional layered or MVC may suffice for speed.

If CQRS is heavily used, consider integrating EventStorming and domain events more deeply or adopting specialised frameworks.