Laravel Best Practices

From the author

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.

— the description by laravel

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

Laravel best practices provides a structured set of guidelines for writing, reviewing, and refactoring Laravel applications. It emphasizes maintaining consistency with existing codebase patterns while offering standardized approaches for common concerns such as database performance, Eloquent usage, security, validation, and architectural design. The skill acts as a reference index, directing developers to specific rule files based on the task at hand.

What it does

Provides a categorized index of rules for various Laravel components.
Promotes consistency by prioritizing existing project patterns over new abstractions.
Offers guidance on database performance, including eager loading and query optimization.
Covers security, validation, routing, and error handling patterns.
Advises on architectural decisions, service classes, and job management.
Encourages the use of native framework features over custom helpers.

When to use it

When writing new controllers, models, or service classes in Laravel.
During code reviews to ensure alignment with established framework patterns.
When refactoring existing code to improve maintainability or security.
When addressing specific issues like N+1 queries or complex Eloquent relationships.
When making architectural decisions regarding application structure.

Advantages

Ensures architectural consistency across the codebase.
Reduces technical debt by discouraging speculative abstractions.
Provides clear, domain-specific guidance for common Laravel tasks.
Helps prevent common pitfalls like hidden N+1 queries and security vulnerabilities.

Usage examples

“How should I structure my Eloquent queries to avoid N+1 issues?”: The agent will reference the database performance and Eloquent rule files to suggest eager loading strategies and proper relationship definitions.
“Review this controller for security and validation best practices.”: The agent will evaluate the code against the security and validation rule files, suggesting improvements for input handling and authorization.
“Should I create a new helper function for this logic?”: The agent will advise on whether to use existing framework features or if the logic warrants a new service class based on architectural guidelines.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/laravel/laravel-best-practices/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip laravel-best-practices.zip -d .agents/skills

Documentation by laravel

Best practices for Laravel, organized as an index of rule files. Each rule file 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 several valid approaches. The best choice is the one the codebase already uses, even if another pattern would be better in theory. Inconsistency is worse than a suboptimal pattern.

Check sibling files and 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.

How to apply

Check the changed files, nearby code, project configuration, and relevant tests for established patterns. Deviate only for a correctness or security defect, and call the deviation out.
Map every affected concern to the rule index below. Read each mapped rule file before editing. Skip unrelated rule files.
Make the smallest coherent change. Keep the application's architecture and naming instead of introducing a second pattern for the same job.
Verify version-sensitive Laravel APIs for the installed version with search-docs, or inspect the installed framework when search-docs is unavailable.
Run the narrowest relevant tests first, then the project's formatting and static-analysis checks when the change warrants them.
Re-read the diff against every mapped rule before finishing.

Rule index

Cross-cutting changes often need more than one rule file.

Concern	Read
Query count, eager loading, indexes, large datasets	`rules/db-performance.md`
Subqueries, aggregates, complex ordering and query plans	`rules/advanced-queries.md`
Models, relationships, scopes, casts	`rules/eloquent.md`
Authentication, authorization, input safety, secrets, uploads	`rules/security.md`
Form Requests and validation rules	`rules/validation.md`
Controllers, route binding, resources, middleware	`rules/routing.md`
Schema changes, columns, foreign keys, indexes	`rules/migrations.md`
Jobs, retries, uniqueness, batches, Horizon	`rules/queue-jobs.md`
Cache lifetime, invalidation, locks, memoization	`rules/caching.md`
Outbound requests, retries, timeouts, fakes	`rules/http-client.md`
Exceptions, reporting, rendering, log context	`rules/error-handling.md`
Events and notifications	`rules/events-notifications.md`
Mailables and mail assertions	`rules/mail.md`
Scheduled tasks and overlap protection	`rules/scheduling.md`
Collections, lazy iteration, bulk operations	`rules/collections.md`
Blade components, attributes, composers	`rules/blade-views.md`
Environment values and application configuration	`rules/config.md`
Tests: coverage, factories, fakes, and assertions	the `testing-best-practices` skill
Naming, helpers, file boundaries, PHP style	`rules/style.md`
Actions, services, dependencies, application structure	`rules/architecture.md`

Decision rules

Prefer framework features and existing application abstractions over new helpers or dependencies.
Avoid speculative abstractions. Extract code when it creates a clear domain boundary, removes meaningful duplication, or makes behavior independently testable.
Keep database access out of Blade views and prevent hidden N+1 queries across controllers, resources, jobs, and serialization.

Files

ATTRIBUTION.mdAdded by AutoGineer924 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md4.5 KiB
rules/advanced-queries.md4.2 KiB
rules/architecture.md6.3 KiB
rules/blade-views.md1.8 KiB
rules/caching.md3.3 KiB
rules/collections.md2.4 KiB
rules/config.blade.phpScript2.1 KiB
rules/db-performance.md5.5 KiB
rules/eloquent.md3.9 KiB
rules/error-handling.md3.1 KiB
rules/events-notifications.blade.phpScript2.6 KiB
rules/http-client.md4.4 KiB
rules/mail.blade.phpScript2.0 KiB
rules/migrations.blade.phpScript3.5 KiB
rules/queue-jobs.md4.3 KiB
rules/routing.md3.7 KiB
rules/scheduling.blade.phpScript2.7 KiB
rules/security.blade.phpScript5.8 KiB
rules/style.md4.2 KiB
rules/validation.md2.9 KiB

rules/eloquent.md

Eloquent best practices

Define precise relationship types

Define the relationship that matches the database association, and declare its concrete return type.

public function comments(): HasMany
{
    return $this->hasMany(Comment::class);
}

public function author(): BelongsTo
{
    return $this->belongsTo(User::class, 'user_id');
}

Use local scopes for reusable queries

Extract reusable query constraints into local scopes to avoid duplication.

Duplicated constraints:

$active = User::where('verified', true)->whereNotNull('activated_at')->get();
$articles = Article::whereHas('user', function ($q) {
    $q->where('verified', true)->whereNotNull('activated_at');
})->get();

Reusable local scope:

#[Scope]
protected function active(Builder $query): Builder
{
    return $query->where('verified', true)->whereNotNull('activated_at');
}

// Usage
$active = User::active()->get();
$articles = Article::whereHas('user', fn ($q) => $q->active())->get();

Apply global scopes sparingly

A global scope silently modifies every query on the model, so queries become hard to debug. Prefer local scopes, and reserve global scopes for universal constraints such as soft deletes or multi-tenancy.

Global scope tradeoff:

class PublishedScope implements Scope
{
    public function apply(Builder $builder, Model $model): void
    {
        $builder->where('published', true);
    }
}

// Admin panels, reports, and jobs now omit drafts unless the scope is removed.

Explicit local scope:

#[Scope]
protected function published(Builder $query): Builder
{
    return $query->where('published', true);
}

Post::published()->paginate(); // Explicit
Post::paginate(); // Admin sees all

Define attribute casts

Use the casts() method for automatic type conversion. If the project convention is the $casts property, follow that convention.

protected function casts(): array
{
    return [
        'is_active' => 'boolean',
        'metadata' => 'array',
        'total' => 'decimal:2',
    ];
}

Cast date and time attributes

Cast a date or timestamp attribute when application code should treat it as a Carbon instance. Eloquent already casts the conventional created_at and updated_at timestamps.

Manual parsing in the template:

{{ Carbon::parse($order->ordered_at)->toDateString() }}

Model cast:

protected function casts(): array
{
    return [
        'ordered_at' => 'datetime',
    ];
}

{{ $order->ordered_at->toDateString() }}
{{ $order->ordered_at->format('m-d') }}

Use `whereBelongsTo()` for relationship queries

whereBelongsTo() expresses the relationship constraint without naming its foreign key.

Foreign key constraint:

Post::where('user_id', $user->id)->get();

Relationship-aware constraint:

Post::whereBelongsTo($user)->get();
Post::whereBelongsTo($user, 'author')->get();

Keep application queries model-aware

Prefer Eloquent models and relationships for model-backed application queries. They preserve casts, scopes, and model table configuration. The query builder and raw SQL require table names. Use them when you intend their lower-level behavior.

Lower-level alternatives:

DB::table('users')->where('active', true)->get();

$query->join('companies', 'companies.id', '=', 'users.company_id');

DB::select('SELECT * FROM orders WHERE status = ?', ['pending']);

Model-aware queries:

User::where('active', true)->get();
Order::where('status', 'pending')->get();

When a query builder operation should follow a model's configured table name, use (new User)->getTable(). For complex joins or raw SQL, explicit table names may be clearer. When the schema can change, cover those table references with tests.

In migrations, use explicit table names rather than application models. Migrations are historical snapshots, but models and their scopes can change after you deploy a migration.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

What our scanner noticed· Low risk

Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Implement
Matt Pocock· Community
A structured workflow for implementing software tasks from specifications or tickets.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository317.5k
Source Driven Development
Addy Osmani· Community
A rigorous process for grounding code implementation in official, version-specific documentation to ensure accuracy and avoid outdated patterns.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository113.9k
Write Swift
Emil Kowalski· Community
A comprehensive guide to writing modern, safe, and performant Swift code following the language's latest idioms and concurrency models.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository54.3k
Cardputer Buddy
AnthropicOfficial
Iterate on the Cardputer-Adv MicroPython app bundle (Claude Buddy, Snake, Hello) after the device is already provisioned via m5-onboard. Use when the user wants to add a new app, push a single changed .py without re-flashing, watch device serial logs, or run a one-shot REPL command. Trigger on "add an app", "push to the cardputer", "tail the device", "run on the device", or follow-up work after /maker-setup.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
Apache-2.0GitHub stars of the source repository46.3k
Typescript Pro
Seth Hobson· Community
An expert TypeScript persona focused on advanced typing, enterprise architecture, and strict type safety.
Software developmentClaude Code
MITGitHub stars of the source repository42.3k
Scala Pro
Seth Hobson· Community
An expert Scala engineer persona specializing in functional programming, distributed systems, and enterprise-grade architecture.
Software developmentClaude Code
MITGitHub stars of the source repository42.3k

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download laravel-best-practices.zip