laravel

When to use

Use this skill for all Laravel-specific code generation and editing tasks, especially when working with:

• Controllers
• Form Requests
• Middleware
• Service Providers
• Jobs / Queued Jobs
• Events / Listeners
• Policies / Gates
• Notifications
• Console Commands
• Config, Routing, and Application Structure

This skill extends the base php-coder skill and applies Laravel conventions on top of the project's general PHP rules.

When NOT to use — components without the framework

A DEPENDENCY PROVES A LIBRARY IS AVAILABLE. ONLY THE ENTRY POINT AND THE
ROUTER PROVE WHICH APPLICATION SHAPE IS RUNNING.
`illuminate/*` PACKAGES WITH NO SKELETON MARKER IS A THIRD STATE, AND THIS SKILL
DOES NOT APPLY TO IT.

Laravel ships its ORM, container, collections and HTTP layer as independently installable packages, usable with no framework present — a published distribution model, not one consumer's arrangement. An application built that way has a custom entry point and a custom router. Routing it here offers a CLI that does not exist, a request-validation primitive that is not wired, and a routes file that was never there: every suggestion confidently wrong, and the reason visible only from the entry point.

The probe set, and its cost. A fixed set of filesystem existence checks plus one manifest read — no directory walk, no content scan, and never re-derived per session. Any ONE marker present means the framework is real:

Probe	Meaning
artisan	the console entry point the skeleton writes
config/app.php	the skeleton's bootstrap config
bootstrap/app.php	the application bootstrap

illuminate/* in composer.json with none of those markers is components-without-the-framework. Say so and route away from this skill rather than answering as though the framework were there.

Implemented deterministically in src/install/detect_php_shape.ts (detectPhpShape), whose PROBE_PATHS is this table and whose verdict names what a wrong route would have offered.

Procedure: Write Laravel code

→ First apply the php-coder skill — it handles project docs, module docs, patterns, and quality tools.

Then add these Laravel-specific checks:

1. Confirm this is a Laravel app — check whether artisan exists.
2. Inspect app structure — classic Laravel, modules (app/Modules/), or domain folders.
3. Check routes and HTTP flow — understand how requests enter the application and where logic belongs.
4. Check test conventions — inspect existing tests in the same domain before writing new code.

Core Laravel principles

• Follow Laravel conventions first unless the project explicitly does otherwise.
• Keep controllers thin — delegate business logic to services/actions.
• Keep Form Requests responsible for validation and authorization.
• Use dependency injection through the container.
• Prefer framework features over custom infrastructure when the built-in solution is sufficient.
• Avoid hidden magic when explicit code is clearer for the project.
• Respect the existing architecture — do not force "pure Laravel" if the project uses modules or service layers.

HTTP layer rules

• Controllers should:
  • accept the request
  • delegate business logic
  • return a response / resource / redirect
• Do not put business logic, calculations, or large data transformations in controllers.
• Use Form Request classes for validation instead of inline controller validation when the request is non-trivial.
• Use route model binding when it improves clarity and matches existing patterns.
• Keep controller actions focused and small.

Validation rules

• Use Form Requests for reusable or non-trivial validation.
• Prefer explicit validation rules over implicit behavior.
• Reuse existing custom rules when available.
• Keep validation close to the HTTP boundary.
• Do not mix validation with persistence or business decisions.

Service layer rules

• Put orchestration and business logic into dedicated services/actions.
• Services should be framework-light when possible.
• A service should have one clear responsibility.
• Prefer constructor injection for dependencies.
• Do not move trivial one-line controller behavior into a service unless the project consistently does that.

Routing rules

• Follow the existing route organization:
  • routes/web.php
  • routes/api.php
  • module-specific route files
• Keep route definitions readable and grouped logically.
• Use route names consistently.
• Apply middleware explicitly and according to project conventions.
• Do not introduce route patterns that differ from the surrounding code without a good reason.

Response rules

• Use the response style already established in the project:
  • Blade views
  • JSON responses
  • API Resources
  • Redirects with flash messages
• For APIs, prefer:
  • consistent status codes
  • structured JSON payloads
  • API Resources when the project uses them
• Do not return raw models directly unless that is already the established project pattern.

Queues, jobs, and async work

• Use Jobs for clearly asynchronous or deferred work.
• Keep Jobs focused on a single responsibility.
• Pass only the data needed by the job.
• Avoid putting excessive domain logic directly into the Job class — delegate to services where appropriate.
• Be mindful of serialization when passing models or objects.

Events and listeners

• Use events for meaningful domain or application events, not for every small action.
• Name events clearly in the past tense when something already happened.
• Keep listeners focused and side-effect oriented.
• Do not introduce event-driven complexity unless it is already part of the project architecture.

Auth, policies, and authorization

• Use Laravel authorization features consistently:
  • policies
  • gates
  • request authorization
• Keep authorization logic out of controllers where possible.
• Reuse existing policies and permission patterns.
• Do not hardcode role checks in multiple places if a policy/gate already exists.

Config and environment

• Read configuration from config files, not directly from env() outside config files.
• Do not introduce new environment variables unless necessary.
• Reuse existing config structure and naming patterns.

Database interaction

• Prefer Eloquent for normal application data access unless the project uses repositories or query objects.
• Use transactions when multiple writes must succeed or fail together.
• Avoid N+1 problems — eager load when appropriate.
• For heavy data access logic, follow the dedicated eloquent skill.

Migrations and schema changes

• Keep migrations focused and reversible.
• Follow existing naming conventions for columns, foreign keys, and indexes.
• Do not mix unrelated schema changes in a single migration.
• Be careful with destructive changes on existing production tables.

Blade and view rules

• Keep views dumb — presentation only.
• Avoid embedding business logic in Blade templates.
• Extract reusable UI pieces into components/partials when it matches project patterns.
• Escape output by default and use raw output only when safe and intentional.

Translations and language files

• Flat dot-notation keys only — 'type.daily_report' => 'Daily Report'. Nested arrays ('type' => ['daily_report' => …]) are forbidden: they break key referencing and make a one-line addition a nested diff.
• Reference with the helper and the same flat key — __('report.type.daily_report'), __('email.report.created.subject', ['number' => $number]).
• Every key exists in every shipped locale. Adding to lang/en/ without lang/de/ is a bug, not a TODO — the app ships to both audiences.
• Never hardcode a user-visible string in PHP.

What NOT to do

• Do not put business logic into controllers, models, or Blade templates.
• Do not validate large requests inline in controllers when Form Requests are more appropriate.
• Do not call env() outside config files.
• Do not introduce new architectural layers unless the project already uses them.
• Do not bypass Laravel features already used consistently in the project.
• Do not return inconsistent API response shapes in an established API.

Output expectations

When generating Laravel code:

• follow Laravel naming conventions
• use dependency injection
• keep classes small and focused
• match the surrounding project structure
• prefer explicit, readable code over clever abstractions
• integrate with existing requests, resources, services, policies, and tests

Output format

1. Laravel code following framework conventions and project architecture
2. All related files (controller, service, request, resource, test) as needed

Do NOT

• Do NOT put business logic in controllers — delegate to services.
• Do NOT use facades in service classes — use dependency injection.
• Do NOT skip middleware for route groups that need authentication.

Known pitfalls

Symptom	Root cause	Fix
A list endpoint fires hundreds of queries / is slow under load	N+1: a relation is accessed inside a loop without eager loading	Eager-load with with('relation'); enable Model::preventLazyLoading() in non-prod to catch it early
Config changes / new env vars have no effect in production	config:cache cached the old config, and env() returns null once config is cached	Read env only in config/*, use config() elsewhere; re-run config:cache on deploy
A form field silently isn't saved	The attribute isn't in $fillable and mass-assignment drops it	Add it to $fillable (or set it explicitly); never blanket-$guarded = [] on user input
Queued jobs never run / run with stale code	No worker is running, or workers weren't restarted after a deploy so they hold the old code in memory	Run/supervise queue:work; queue:restart on every deploy
Timestamps or times are off by hours	Comparing/formatting a Carbon instance without honoring config('app.timezone') vs the DB's UTC storage	Store UTC; convert for display; set the app timezone explicitly, don't assume server local time

Gotcha

• env() only works in config files — use config() everywhere else.
• Don't mix Route::resource() with single-action controllers — pick the project's convention.
• Don't return Eloquent models directly — always use API Resources.
• Don't bypass existing middleware stacks when adding new routes.

Auto-trigger keywords

• Laravel
• controller
• service
• middleware
• route
• application structure

Security audit checks (from security-audit)

Laravel-specific audit list (carved out of the generic security-audit skill, 2026-07-12):

• env() in non-config files (leaks in debug mode)
• Debug mode (APP_DEBUG=true) in production
• Missing $fillable on models used with request()->all()
• Route::any() exposing unintended HTTP methods
• Missing rate limiting on login/register/password-reset
• Broadcast channels without proper authorization
• Missing encryption on sensitive cookie/session data