Service Layer (Application Services)

When to use

• The user wants one class per use case that coordinates domain objects and repositories to carry out an operation.
• The user wants to move business logic out of controllers so the delivery layer only translates requests and responses.
• The user wants a single place that begins and commits the transaction wrapping a whole use case.

When NOT to use

• Do not reach for a service layer as the place to put domain rules that belong on the entity or value object itself.
• Do not add an application service that only forwards a call straight to a repository with no coordination or transaction.

Core guidance

• Give each use case its own service method — Model each use case as one application service (or one method on a focused service) with a clear name like PlaceOrder or registerUser.
• Own the transaction at the service boundary — Begin and commit the transaction inside the application service so the whole use case is one atomic unit of work, rolling back on failure.

Quick recipe

1. Create one application service for the use case with a plain input, e.g. final class PlaceOrder whose execute(PlaceOrderInput $input): OrderPlaced names the operation. (verify: The service takes a plain input object and no framework request)
2. In execute(), open a transaction, load aggregates from injected repositories, call their behavior, persist them, then commit — rolling back on any failure. (verify: The whole use case commits atomically, and a thrown exception rolls it back)
3. Have the controller map the request to the input DTO, call the service, and turn its result into a response — with no business logic of its own. (verify: The controller only translates request to input and result to response)

Best practices

• Have the service accept a plain input object or scalars and return a plain result, not the framework request or an ORM entity, so it stays independent of the delivery mechanism
• Inject repositories and external gateways into the service as interfaces, so the use case is wired to abstractions and can be tested with fakes
• Let the service coordinate — load aggregates, call their behavior, save them — and push the actual rules down into the domain objects it uses

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. The service swelling into a transaction script — Letting all the business rules pile up inside the service method produces a long procedural transaction script with an anemic domain underneath. Fix: Move each rule onto the entity or value object it belongs to, leaving the service to load, invoke behavior, and save.
2. Framework request objects leaking into the service — Passing the raw HTTP request or session into the application service ties the use case to the web delivery mechanism. Fix: Have the controller extract the needed values into a plain input DTO and pass that to the service, keeping the service delivery-agnostic.
3. Nested services with tangled transactions — Having one application service call another, each opening its own transaction, produces nested or overlapping transaction scopes that are hard to reason about. Fix: Keep one transaction boundary per top-level use case; extract shared steps into domain services or plain collaborators that do not open their own transaction.

Version notes

• Immutable input DTOs with PHP 8.1 readonly (PHP >=8.1) — PHP 8.1 readonly promoted properties make the service's input and result DTOs immutable in a couple of lines, so the use case receives a fixed request.
• Property hooks tidy result DTOs in PHP 8.4 (PHP >=8.4) — From PHP 8.4, property hooks let a result DTO expose a computed field (a formatted total) without a separate getter, keeping the service's output object small.

Security

• Not applicable — no I/O, auth, or untrusted input.

Testing

• Activation and decision behavior are verified in eval/scenarios/architecture/service-layer.yaml.
• Inject repositories and external gateways into the service as interfaces, so the use case is wired to abstractions and can be tested with fakes.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Prerequisites: architecture/dependency-inversion
Related: architecture/cqrs, architecture/repository-pattern