When a Stripe client appears in dozens of places, each with its own configuration, the application becomes fragile and hard to maintain. The solution is to gather all wiring in one place, the composition root, so the rest of the code stays clean and testable.
The composition root concept appears in many contexts, and a visual cue helps. 
It shows where wiring lives in a PHP application.
Scattered StripeClient constructions appear in controllers, services, console commands, and even a forgotten Twig extension. Each construction uses a different configuration, making key rotation painful.
Mark Seemann introduced the term in his .NET book, describing the composition root as the single place near the application entry point where abstractions bind to implementations. In PHP this means that when a request, CLI call, or queue message arrives, one piece of code builds the needed use case with all dependencies already wired.
The plainest version is a function that calls constructors in order, known as pure DI. The function lives in src/Bootstrap and the front controller calls it, keeping the domain untouched.
Symfony or Laravel apps have hundreds of services, and writing each constructor call by hand becomes tedious. The framework container autowires types and resolves the graph, but the container must stay at the edge, not inside the domain.
A service locator anti pattern hides dependencies behind a container interface, preventing straightforward testing. PlaceOrder should depend on typed interfaces, not on the container or string keys.
In services.yaml the mapping of interfaces to concrete classes resides in the composition root, for example OrderRepository maps to DoctrineOrderRepository and PaymentGateway maps to HttpPaymentGateway. The configuration is read once, and the rest of the code works with abstractions only.
A transactional decorator wraps the use case, opening a transaction before execution and committing or rolling back based on outcome. The decorator implements the same interface, so callers remain unaware of the wrapping.
Pushing wiring to one edge isolates the domain from framework details, allowing in‑memory fakes for unit tests without booting a container. Swapping Doctrine for raw PDO or changing the HTTP client only requires editing the binding file.
The trade favors concentrating concrete knowledge in a single file, letting the interesting files stay focused on business rules. This separation lets the application survive framework upgrades with minimal impact.
The diagram below visualizes the layered structure. 
The diagram highlights the clean separation that the composition root enforces. Developers can read the binding file and know every concrete class used.
The composition root is a seam that pushes framework decisions to the edge, enabling the domain to outlive the framework. When the root is well defined, the application remains clear, testable, and adaptable.
Comments
Please log in or register to join the discussion