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/http-client.md

HTTP client best practices

Set explicit timeouts

Laravel's HTTP client has a 30-second response timeout by default. Choose response and connection timeouts that fit the service and the calling request or job. Retries can multiply the total elapsed time.

Less resilient:

$response = Http::get('https://api.example.com/users');

Preferred:

$response = Http::connectTimeout(3)
    ->timeout(5)
    ->get('https://api.example.com/users');

Define shared settings in a macro or a dedicated client:

Http::macro('github', function () {
    return Http::baseUrl('https://api.github.com')
        ->connectTimeout(3)
        ->timeout(10)
        ->withToken(config('services.github.token'));
});

$response = Http::github()->get('/repos/laravel/framework');

Retry only safe operations

Retry transient connection failures, rate-limit responses, and server errors with an appropriate delay. Retry idempotent requests such as GET when the operation can safely run more than once. Retry a state-changing request only when the remote API supports an idempotency key or provides equivalent duplicate protection.

Unsafe without an idempotency guarantee:

$response = Http::retry([100, 500, 1000])
    ->post('https://api.example.com/v1/charges', $data);

Safe for an idempotent request:

$response = Http::connectTimeout(3)
    ->timeout(10)
    ->retry([100, 500, 1000], 0, function (Throwable $exception) {
        return $exception instanceof ConnectionException
            || ($exception instanceof RequestException
                && ($exception->response->serverError() || $exception->response->status() === 429));
    })
    ->get('https://api.example.com/data');

For a supported state-changing API, send a stable idempotency key for every attempt:

$response = Http::withHeaders(['Idempotency-Key' => $paymentAttempt->uuid])
    ->connectTimeout(3)
    ->timeout(10)
    ->retry([100, 500, 1000], 0, function (Throwable $exception) {
        return $exception instanceof ConnectionException
            || ($exception instanceof RequestException
                && ($exception->response->serverError() || $exception->response->status() === 429));
    })
    ->post('https://api.example.com/v1/charges', $data);

Handle errors explicitly

By default, the HTTP client returns responses for 4xx and 5xx status codes instead of throwing. Inspect the expected statuses or call throw() before consuming a success payload.

Unsafe when a success payload is expected:

$user = Http::get('https://api.example.com/users/1')->json();

Preferred:

$user = Http::connectTimeout(3)
    ->timeout(5)
    ->get('https://api.example.com/users/1')
    ->throw()
    ->json();

When graceful degradation is required, handle expected alternatives explicitly:

$response = Http::connectTimeout(3)
    ->timeout(5)
    ->get('https://api.example.com/users/1');

if ($response->successful()) {
    return $response->json();
}

if ($response->notFound()) {
    return null;
}

$response->throw();

Pool independent requests

Use Http::pool() when several independent requests can run concurrently. Pooling changes execution time, not error handling. Inspect or throw for each response as needed.

use Illuminate\Http\Client\Pool;

$responses = Http::pool(fn (Pool $pool) => [
    $pool->as('users')->connectTimeout(3)->timeout(5)
        ->get('https://api.example.com/users'),
    $pool->as('posts')->connectTimeout(3)->timeout(5)
        ->get('https://api.example.com/posts'),
]);

$users = $responses['users']->throw()->json();
$posts = $responses['posts']->throw()->json();

Fake HTTP requests in tests

Use Http::fake() for external integrations, and use Http::preventStrayRequests() when an unexpected real request should fail the test. Also test timeouts, connection failures, and error responses that the application handles.

it('syncs a user from the API', function () {
    Http::preventStrayRequests();

    Http::fake([
        'api.example.com/users/1' => Http::response([
            'name' => 'John Doe',
            'email' => '[email protected]',
        ]),
    ]);

    (new UserSyncService)->sync(1);

    Http::assertSent(fn (Request $request) =>
        $request->url() === 'https://api.example.com/users/1'
    );
});

For example, to test the integration's failure path, fake a connection failure:

Http::fake([
    'api.example.com/*' => Http::failedConnection(),
]);

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