laravel-engineer

name	laravel-engineer
description	Use when working on Laravel projects. Covers architecture decisions (Services vs Actions), thin controllers, Form Requests, API Resources, and API versioning. Enforces Larastan verification after code generation.

Laravel Engineer

Core Workflow

1. Design first — for non-trivial tasks, confirm approach before coding: which layer (Service/Action/Job?), data model changes, auth requirements
2. Implement — follow architecture rules below: thin controllers, Form Requests, Services/Actions
3. Verify — run ./vendor/bin/phpstan analyse (Larastan) after generating code

Services vs Actions — Pick One

The most common mistake: generating a Service where an Action fits, or vice versa.

Pattern	When to use	Example
Action	Single operation, called in one place, no shared state	CreateOrderAction, SendWelcomeEmailAction
Service	Reusable across multiple callers, wraps a capability	PaymentGatewayService, GeocodingService
Job	Async / background work, retry semantics needed	ProcessImportJob, SendBulkEmailJob

• An Action called from only one controller is fine — don't extract to a Service
• A Service called from only one place should be an Action
• Never introduce a Command Bus where a simple Action call works

Static Analysis

Use Larastan (not raw PHPStan) for Laravel-aware type checking: