using-laravel-entry-points ยท diff
git:20260922.00e7bbe to git:20260922.7ecf42a
17 added, 39 removed. Audit A to A.
---
name: using-laravel-entry-points
- description: Use Laravel controllers, commands, jobs, listeners, and other entry points without leaking application or domain logic into them.
+ description: Implement or refactor Laravel controllers, commands, jobs, listeners, and scheduled tasks. Use for endpoints, authentication, request validation, simple reads, or extracting business orchestration into Actions.
---
- # Using Laravel Entry Points
-
- Laravel entry points receive external stimuli and connect them to the application.
-
- Common entry points include:
-
- - Controllers
- - Console Commands
- - Jobs
- - Listeners
- - Scheduled tasks
-
- Keep entry points thin.
-
- When an entry point triggers meaningful application behavior, delegate that
- behavior to an Application Action.
+ # Laravel entry points
- Prefer:
+ Keep controllers, commands, jobs, listeners, policies, and providers in Laravel's usual locations. Entry points authenticate, validate or normalize transport input, and translate application results or exceptions into transport output.
- Controller -> Action
- Command -> Action
- Job -> Action
- Listener -> Action
+ For meaningful business operations, use `Controller -> Action`, `Command -> Action`, `Job -> Action`, or `Listener -> Action`. Pass explicit input and an actor when authorization is required; the Action authorizes its use case. Background work must have an intentional actor or trusted system policy, not an accidental authorization bypass.
- Entry points may:
+ ```php
+ public function destroy(Request $request, Order $order, CancelOrder $cancelOrder): Response
+ {
+ $cancelOrder->handle($request->user(), $order->id);
- - receive framework-specific input
- - validate or normalize transport-specific input
- - create Application Data objects
- - invoke Actions
- - transform Action results into framework-specific output
- - perform small, local technical side effects
+ return response()->noContent();
+ }
+ ```
- Entry points must not:
+ Assume authentication middleware and imports for Laravel Request/Response, the domain Order, and the application CancelOrder. Route binding resolves the model; the Action still authorizes. Map domain exceptions centrally using Laravel's exception handling or an appropriate local adapter. Do not add HTTP status codes to domain exceptions.
- - implement business rules
- - become the primary implementation of a use case
- - contain complex application orchestration
+ For structured input, map validated request values into a Data object when useful. Domain invariants must also be enforced for non-HTTP callers.
- Do not create an Action merely to wrap a trivial framework-specific operation.
+ ## Keep simple operations simple
- If behavior represents a business rule, move it to the Domain.
+ A simple list/detail read can use Eloquent directly, authorize with policies/gates, and return a Resource. Do not create an Action just to wrap a query or trivial framework operation. Move meaningful business behavior and coordination into Application; move invariants into Domain.
- If behavior represents an application use case or meaningful orchestration,
- move it to an Application Action.
+ A listener may perform a small technical side effect directly. A multi-step business reaction should invoke an Action. External effects triggered by transactional changes must wait until commit.
- If behavior is a small technical side effect with no meaningful application
- semantics, it may remain in the entry point.
+ Actions do not dispatch concrete `App\Jobs` classes. Prefer business events for asynchronous follow-up; reserve contracts for concrete infrastructure capabilities.