/laravel-best-practices

name: laravel-best-practices
description: "Apply this skill whenever writing, reviewing, or refactoring Laravel PHP code. This includes creating or modifying controllers, models, migrations, form requests, policies, jobs, scheduled commands, service classes, and Eloquent queries. Triggers for N+1 and query performance issues, caching strategies, authorization and security patterns, validation, error handling, queue and job configuration, route definitions, and architectural decisions. Also use for Laravel code reviews and refactoring existing Laravel code to follow best practices. Covers any task involving Laravel backend PHP code patterns."
license: MIT
metadata:
  author: laravel

Laravel Best Practices

Best practices for Laravel, prioritized by impact. Each rule teaches what to do and why. For exact API syntax, verify with `search-docs`.

Consistency First

Before applying any rule, check what the application already does. Laravel offers multiple valid approaches — the best choice is the one the codebase already uses, even if another pattern would be theoretically better. Inconsistency is worse than a suboptimal pattern.

Check sibling files, related controllers, models, or tests for established patterns. If one exists, follow it — don't introduce a second way. These rules are defaults for when no pattern exists yet, not overrides.

Quick Reference

1. Database Performance → `rules/db-performance.md`

• Eager load with `with()` to prevent N+1 queries
• Enable `Model::preventLazyLoading()` in development
• Select only needed columns, avoid `SELECT *`
• `chunk()` / `chunkById()` for large datasets
• Index columns used in `WHERE`, `ORDER BY`, `JOIN`
• `withCount()` instead of loading relations to count
• `cursor()` for memory-efficient read-only iteration
• Never query in Blade templates

2. Advanced Query Patterns → `rules/advanced-queries.md`

• `addSelect()` subqueries over eager-loading entire has-many for a single value
• Dynamic relationships via subquery FK + `belongsTo`
• Conditional aggregates (`CASE WHEN` in `selectRaw`) over multiple count queries
• `setRelation()` to prevent circular N+1 queries
• `whereIn` + `pluck()` over `whereHas` for better index usage
• Two simple queries can beat one complex query
• Compound indexes matching `orderBy` column order
• Correlated subqueries in `orderBy` for has-many sorting (avoid joins)

3. Security → `rules/security.md`

• Define `$fillable` or `$guarded` on every model, authorize every action via policies or gates
• No raw SQL with user input — use Eloquent or query builder
• `{{ }}` for output escaping, `@csrf` on all POST/PUT/DELETE forms, `throttle` on auth and API routes
• Validate MIME type, extension, and size for file uploads
• Never commit `.env`, use `config()` for secrets, `encrypted` cast for sensitive DB fields

4. Caching → `rules/caching.md`

• `Cache::remember()` over manual get/put
• `Cache::flexible()` for stale-while-revalidate on high-traffic data
• `Cache::memo()` to avoid redundant cache hits within a request
• Cache tags to invalidate related groups
• `Cache::add()` for atomic conditional writes
• `once()` to memoize per-request or per-object lifetime
• `Cache::lock()` / `lockForUpdate()` for race conditions
• Failover cache stores in production

5. Eloquent Patterns → `rules/eloquent.md`

• Correct relationship types with return type hints
• Local scopes for reusable query constraints
• Global scopes sparingly — document their existence
• Attribute casts in the `casts()` method
• Cast date columns, use Carbon instances in templates
• `whereBelongsTo($model)` for cleaner queries
• Never hardcode table names — use `(new Model)->getTable()` or Eloquent queries

6. Validation & Forms → `rules/validation.md`

• Form Request classes, not inline validation
• Array notation `['required', 'email']` for new code; follow existing convention
• `$request->validated()` only — never `$request->all()`
• `Rule::when()` for conditional validation
• `after()` instead of `withValidator()`

7. Configuration → `rules/config.md`

• `env()` only inside config files
• `App::environment()` or `app()->isProduction()`
• Config, lang files, and constants over hardcoded text

8. Testing Patterns → `rules/testing.md`

• `LazilyRefreshDatabase` over `RefreshDatabase` for speed
• `assertModelExists()` over raw `assertDatabaseHas()`
• Factory states and sequences over manual overrides
• Use fakes (`Event::fake()`, `Exceptions::fake()`, etc.) — but always after factory setup, not before
• `recycle()` to share relationship instances across factories

9. Queue & Job Patterns → `rules/queue-jobs.md`

• `retry_after` must exceed job `timeout`; use exponential backoff `[1, 5, 10]`
• `ShouldBeUnique` to prevent duplicates; `ShouldBeUniqueUntilProcessing` for early lock release
• Always implement `failed()`; with `retryUntil()`, set `$tries = 0`
• `RateLimited` middleware for external API calls; `Bus::batch()` for related jobs
• Horizon for complex multi-queue scenarios

10. Routing & Controllers → `rules/routing.md`

• Implicit route model binding
• Scoped bindings for nested resources
• `Route::resource()` or `apiResource()`
• Methods under 10 lines — extract to actions/services
• Type-hint Form Requests for auto-validation

11. HTTP Client → `rules/http-client.md`

• Explicit `timeout` and `connectTimeout` on every request
• `retry()` with exponential backoff for external APIs
• Check response status or use `throw()`
• `Http::pool()` for concurrent independent requests
• `Http::fake()` and `preventStrayRequests()` in tests

12. Events, Notifications & Mail → `rules/events-notifications.md`, `rules/mail.md`

• Event discovery over manual registration; `event:cache` in production
• `ShouldDispatchAfterCommit` / `afterCommit()` inside transactions
• Queue notifications and mailables with `ShouldQueue`
• On-demand notifications for non-user recipients
• `HasLocalePreference` on notifiable mo