padosoft-laravel-scaffolding
Use this skill when adding something new to a Laravel application — an endpoint, a controller, a service, a CRUD backend, a queued job, a test — "make me the API for X", "add the CRUD for Y", "I need
SKILL.mdskills/padosoft-laravel-scaffolding/SKILL.md
GitHubLaravel scaffolding
The code is the easy part. What gets forgotten is the wiring: the route, the policy, the binding, the test — each of which fails in its own quiet way.
The conventions the generated code must follow are in padosoft-laravel-conventions; the checks it must
survive are in padosoft-laravel-security-review.
0. Ask first, in one batch
- what: endpoint, controller, service, CRUD, job, test;
- which domain/module it belongs to — and whether that module exists;
- who may call it: guest, authenticated, a role, an owner. This answer decides the policy, and it is the one most often left implicit;
- the shape of input and output, and whether the response is shared with a frontend that already expects a shape;
- synchronous or queued, and if queued, on which connection and queue.
If the answer to "who may call it" is "the authenticated user", ask the follow-up: any authenticated user,
or only the owner of the record? That distinction is the whole of SEC-IDOR-001.
1. Endpoint / controller — the file list
| # | File | Skipping it means |
|---|---|---|
| 1 | The route, in the right route file and group | 404, or worse: the route exists without the group's middleware |
| 2 | FormRequest |
Validation lives in the controller, or nowhere |
| 3 | DTO | An untyped array crosses every boundary |
| 4 | Controller | — |
| 5 | Service / action | The logic is in the controller and is not testable without HTTP |
| 6 | Policy + authorize() called |
A policy that exists and is never invoked is not a control |
| 7 | JsonResource / response shape |
The model is serialised whole, including what should not leave |
| 8 | Feature test, happy and failure path | — |
| 9 | Route list check | The route answers on the verb and path you think |
Steps 1, 6 and 9 are the ones that fail silently: everything compiles, the endpoint answers, and the authorisation was never asked.
php artisan route:list --path=<fragment> # verb, path, middleware, action
Read the middleware column: that is where you see whether auth actually applies.
2. Service
final class DoTheThing
{
public function __construct(private readonly ThingRepository $repo) {}
public function __invoke(DoTheThingData $data): Thing
{
// one responsibility; no HTTP, no request(), no auth() in here
}
}
- No
request(), noauth(), nosession()inside a service. Whatever it needs arrives as an argument, or it cannot be called from a command, a job or a test. - Register it in the container only if it needs binding; otherwise let autowiring do it.
- A service returning
boolto mean "it worked" is usually hiding a failure the caller needs — seepadosoft-failure-visibility.
3. CRUD backend
Beyond the endpoint list: for each of index / show / store / update / destroy, decide who may — they are
rarely the same answer — and whether destroy is a soft delete. If it is, every listing and count elsewhere
needs to know (padosoft-laravel-conventions §4).
For the listing: pagination from the start, not "for now it returns everything". The dataset that makes it a problem arrives in production, not in the fixture.
4. Queued job
php artisan queue:work --queue=<name> # does the queue you dispatched to actually have a worker?
- The job orchestrates, the service implements.
- Set
$tries,$backoffand$timeoutdeliberately; the defaults are a decision you did not make. failed()handles the permanent failure — and that is a place people leave empty, so the failure becomes a row nobody reads.- Dispatch after commit if the job reads a row the current transaction is writing.
- Retryable vs permanent: fail explicitly on a permanent error rather than throwing something the queue retries sixteen times.
5. Test
A test written together with the code, not after: see padosoft-test-integrity for what makes a test
real. The minimum here:
- the happy path;
- the authorisation path — a user who must not, gets a 403;
- one failure path, actually provoked;
- database state restored between tests, and your own teardown before the framework's.
Before declaring it done
php artisan route:list --path=<fragment> # route + middleware
grep -rn "authorize(" app/Http/Controllers/<Controller>.php
php artisan test --filter=<TestClass>
vendor/bin/pint --test && vendor/bin/phpstan analyse # or the project's equivalents
Gotchas
- A route outside the right group loses the group's middleware — auth included — and still answers 200.
- A policy is not a control until
authorize()is called. Registering it is not enough. - A
FormRequestthat the controller ignores (readingall()instead ofvalidated()) validates and then hands over the unvalidated payload anyway. - A job dispatched to a queue with no worker is a silent hole: everything returns 202, nothing runs.
- Do not invent the layout. Read where the neighbouring modules put their services, requests and routes before creating files: this list is the shape, the repository has the paths.
Checklist
- Route in the right file and group;
route:listshows the expected middleware - FormRequest, and the controller reads
validated()/ the DTO — neverall() - Logic in the service; no
request()/auth()inside it - Policy written and
authorize()called on the path - Response through a resource, not the raw model
- Job: tries, backoff, timeout,
failed(), after-commit dispatch if needed, worker on that queue - Tests: happy, authorisation, one real failure path
- Pint and static analysis clean
Final report
Created: <what> · module: <where>
Files: route · request · dto · controller · service · policy · resource · test
Authorisation: <who may, and where it is enforced>
Queue: <name> · tries/backoff/timeout · worker verified: yes|no
route:list middleware: <what it shows>
Pint / static analysis / tests: PASS | FAIL <detail>