Refactoring a Symfony application with Clean Architecture and DDD
How I moved a growing Symfony platform from technical folders to bounded contexts, inward dependencies, explicit ports, and architecture checks with Deptrac.
How to build a durable payment workflow around FlexPay using Orders, Payment Transactions, signed webhooks, idempotent fulfillment, and a migration path from a legacy billing model.
Using named domain exceptions to express rejected business rules, roll back commands, cross Symfony Messenger safely, produce RFC 9457 problem responses, and separate expected failures from real incidents.
A practical testing architecture for combining fast domain tests, executable Behat application specifications, in-memory ports, deterministic time, real Symfony boundaries, and focused infrastructure tests.
Read
Need a software engineer?
Send the goal, stack, and timeline. I'll reply with a next step.
A Symfony project can reach a point where every feature touches a controller, entity, repository, and service in four different folders. The directory tree shows technical roles but hides the business area each class belongs to.
At the beginning, this structure feels simple. Then the application grows. The Service directory becomes a collection of unrelated business logic, controllers start making business decisions, and changing a payment provider or database detail requires modifications everywhere.
I experienced this directly while building Leganews, a legal information platform I co-founded. I had a real product, existing users, and legacy data that could not simply disappear while I redesigned the codebase.
So this was not a greenfield architecture exercise. I refactored the system to make its business boundaries visible, protect the domain from Symfony and Doctrine, and allow the platform to continue evolving without turning every change into a risky operation.
I combined Clean Architecture, Domain-Driven Design, Symfony's dependency injection container, Messenger, external Doctrine mappings, and Deptrac. The examples include the configuration needed to apply the same boundaries in another Symfony project.
There is nothing inherently wrong with this structure. Symfony provides sensible defaults, and for a small application they are often enough.
The problem appears when the product contains several business areas. A billing change may be spread across Controller, Entity, Repository, and Service. The directory tree tells me which technical tool a class uses, but not which business capability it belongs to.
As the platform grew, I needed the code to answer more useful questions:
Is this part of Identity, Billing, Monitoring, or the legal Corpus?
Which rules belong to the business, and which are only Doctrine or Symfony details?
Can Billing change without accidentally breaking Monitoring?
Can a use case be tested without a database or an HTTP request?
That is where DDD and Clean Architecture became useful to me.
Domain-Driven Design helps me organize the system around the language and boundaries of the business. Instead of one large application model, I define bounded contexts such as Identity, Billing, Access, Corpus, and Monitoring.
Clean Architecture gives me a dependency rule: source-code dependencies point toward the business rules, not away from them.
In my implementation, the direction looks like this:
Mermaid
The meaning is simple:
Domain contains business concepts and rules.
Application coordinates use cases.
Infrastructure implements technical details such as Doctrine, Redis, and external APIs.
Presentation translates HTTP or console input into application messages.
The domain does not know that Symfony, Doctrine, PostgreSQL, or Redis exists.
Now, when an engineer works on bookmarks, most of the relevant code is under Monitoring. The folder structure communicates product language before it communicates framework details.
One important rule: Shared is not a place for anything I cannot classify. It contains concepts that are truly generic across contexts. If a class uses product language, it probably belongs to a bounded context.
In a standard Symfony project, Kernel.php lives directly under src/. I moved it to:
Plain text
src/Shared/Infrastructure/Framework/Kernel.php
This does not magically create Clean Architecture, but it makes an important design decision visible: Symfony is the runtime that boots my application. It is infrastructure, not the center of the business model.
Because the class moved, the HTTP and console entry points import its new namespace.
Moving the Kernel is optional in your project. The essential part is the dependency rule. For me, the move made that rule easier to see and harder to forget.
Why exclude entities and value objects? Because they are domain objects, not container services. They should be created by the domain or application with explicit data, not fetched from Symfony's container.
With autowiring enabled, a handler can depend on a domain interface:
The application layer does not ask for EntityManagerInterface or a Doctrine repository. It asks for the capability it needs: a BookmarkRepository.
When there is only one implementation, Symfony can resolve it without me adding repetitive aliases. In my application, for example, the container resolves:
Mermaid
When multiple implementations exist, I configure the selection explicitly. My payment gateway is a good example: I have an in-memory implementation and a FlexPay implementation, then expose the configured gateway to the application.
This is the practical role of Dependency Inversion: the use case owns the interface, while Symfony chooses the technical adapter at the composition root.
Notice what is absent: no controller, no request, no entity manager, and no Doctrine mapping attributes.
I also pass the current time into the domain. The entity does not call new DateTimeImmutable() to discover "now." This makes time explicit and allows tests to control it.
This interface is not an abstraction added "just in case." It is a port required by an actual use case. The domain owns its language, while Infrastructure provides the implementation.
Then each bounded context gets its own Doctrine mapping configuration:
YAML
# config/packages/doctrine.yamldoctrine:orm:entity_managers:default:mappings:Monitoring:is_bundle:falsetype: xml
dir:'%kernel.project_dir%/config/doctrine/Monitoring'prefix:'Leganews\Monitoring\Domain\Model'Billing:is_bundle:falsetype: xml
dir:'%kernel.project_dir%/config/doctrine/Billing'prefix:'Leganews\Billing\Domain\Model'
Repeat the mapping block for the other contexts.
This configuration is slightly more verbose than attributes, but it keeps persistence metadata at the edge. I can read and unit-test the entity as an ordinary PHP object.
The controller is intentionally boring. Authentication, request mapping, and response serialization belong here. The decision about how a bookmark is created does not.
I use Symfony Messenger behind my own small CommandBus, QueryBus, MessageBus, and EventDispatcher contracts.
The Symfony adapters live in Infrastructure. This keeps handlers independent from Messenger's runtime API while still allowing me to use useful attributes such as #[AsMessageHandler].
Commands change state, so my command bus adds a Doctrine transaction middleware. Queries read state and do not need that transaction. Events allow no handlers because announcing something should not require a subscriber to exist.
The correlation middleware carries one identifier through the message chain, which makes logs from a complete operation easier to follow.
This separation is not only stylistic. It gives every message a clear purpose and lets me apply different middleware policies to different operations.
The important line is Domain: ~. Domain classes are not allowed to depend on another architectural layer or on the Symfony runtime.
I deliberately model Symfony attributes separately. An application handler may use a passive #[AsMessageHandler] marker without receiving Symfony's message bus as a runtime dependency.
Run the check with:
Bash
vendor/bin/deptrac --no-progress
At the time of writing, the project reports zero unskipped violations. I also keep a visible skip_violations list for accepted dependencies such as Symfony's UUID implementation.
That list matters. A skipped violation is not the same as "the architecture is perfect." It is an explicit compromise that can be reviewed and removed later instead of a dependency hidden in the codebase.
My current rules enforce the global layer direction. They do not yet enforce complete isolation between every bounded context. For example, a domain class in one context can still reference a domain value object from another context without Deptrac rejecting it.
If your system requires stronger context isolation, add a layer for each context or use additional collectors. Start with rules your team can understand and maintain, then make them stricter as the boundaries become stable.
This architecture was shaped by a real constraint: Leganews already had valuable data in a legacy MariaDB application, while the refactored platform uses PostgreSQL.
As a co-founder, I could not treat the rewrite as only a code-quality project. The architecture had to preserve users, legal content, subscriptions, orders, bookmarks, and their relationships.
I isolated the old database as a separate Doctrine DBAL connection:
The order represents data dependencies. Users must exist before their bookmarks; products and prices must exist before orders; organizations must exist before memberships.
Each plan implements an application-level migration contract, while SQL and legacy schema knowledge remain in Infrastructure. The importer owns orchestration, reporting, conflict handling, and row failures.
Mermaid
I also preserved stable identifiers where possible. That reduced broken references while the new model introduced clearer concepts and boundaries.
This gave me a practical refactoring path:
Model one business capability in its bounded context.
Put the new use cases behind application commands and queries.
Adapt persistence and external systems at the Infrastructure edge.
Import legacy data in dependency order.
Verify counts, conflicts, and rejected rows before switching traffic.
The lesson is that Clean Architecture is not only useful after migration. It helps create a safe place to migrate into.
The repository interface lets my application tests run with in-memory adapters and a controllable clock.
A use-case scenario reads like this:
Plain text
Scenario: Creating a bookmark starts a private collection
Given current time is "2026-07-13 10:00:00"
When a bookmark is created through the application with the following details:
| userId | name | description | visibility |
| ... | Research folder | | private |
Then the bookmark should keep the following presentation:
| name | visibility | updatedAt |
| Research folder | private | 2026-07-13 10:00:00 |
And the bookmark creation should be announced
This test drives the real command bus and handler, but replaces the database with an in-memory repository. It verifies the application boundary without turning every business scenario into a slow browser test.
I use different tests for different risks:
PHPUnit for entities, value objects, policies, and isolated domain rules.
Behat for commands and queries at the application boundary.
Symfony functional tests for routing, security, serialization, Doctrine mappings, and other framework integrations.
Deptrac then checks something tests usually do not: whether the dependency direction is still valid.
An architecture rule that only runs on one developer's machine will eventually be bypassed.
My main quality command includes formatting, Symfony configuration linting, static analysis, a Rector dry run, and Deptrac. The essential part for this article is simple:
There are more files because commands, handlers, ports, and adapters have distinct responsibilities.
External Doctrine mappings are more verbose than entity attributes.
A team must agree on the domain language, or the bounded contexts become technical folders with better names.
Deptrac only protects the rules you configure. It cannot decide whether a business concept belongs in the correct context.
Not every CRUD operation needs a complex aggregate or a domain event.
I try to stay pragmatic. The goal is not to maximize interfaces and layers. The goal is to keep important business decisions independent from delivery and persistence details.
If a simple read model can answer a query, I use it. If only one adapter exists, I let Symfony autowire it. If I accept an architectural exception, I record it explicitly instead of pretending it does not exist.
Refactoring Leganews around Clean Architecture and DDD changed more than the directory tree.
Bounded contexts made business ownership visible.
Domain objects became plain PHP objects with explicit rules.
Repository and bus contracts inverted dependencies toward the application core.
Symfony's DI container assembled the implementation at the edges.
External Doctrine mappings kept ORM details outside the domain.
Messenger gave commands, queries, and events distinct execution policies.
Deptrac turned architectural intent into an automated check.
Ordered migration plans allowed the new model to coexist with legacy data during the refactor.
The result is still a Symfony application. Symfony handles delivery, dependency injection, messaging, and persistence at the edges, while the domain keeps its own model. I can now change an infrastructure choice without treating it as a permanent business rule.
