# Laravel Best Practices

> Laravel best practices and architecture patterns for building production-ready applications. Use when writing, reviewing, or refactoring Laravel code to ensure proper patterns for service providers, dependency injection, security, Eloquent, and performance.

- Skill: `paulofelipem/laravel-best-practices` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add paulofelipem/laravel-best-practices`
- Raw SKILL.md: https://api.skillmd.com/api/skills/paulofelipem/laravel-best-practices/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- License: MIT
- Author: PauloFelipeM (https://skillmd.com/u/paulofelipem)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/paulofelipem/laravel-best-practices

---


# Laravel Best Practices

Comprehensive best practices guide for Laravel applications. Contains 40 rules across 10 categories, prioritized by impact to guide automated refactoring and code generation.

## When to Apply

Reference these guidelines when:

- Writing new Laravel controllers, services, or models
- Implementing authentication and authorization
- Reviewing code for architecture and security issues
- Refactoring existing Laravel codebases
- Optimizing performance or database queries
- Building microservices or queue-based architectures

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Architecture | CRITICAL | `arch-` |
| 2 | Dependency Injection | CRITICAL | `di-` |
| 3 | Error Handling | HIGH | `error-` |
| 4 | Security | HIGH | `security-` |
| 5 | Performance | HIGH | `perf-` |
| 6 | Testing | MEDIUM-HIGH | `test-` |
| 7 | Database & ORM | MEDIUM-HIGH | `db-` |
| 8 | API Design | MEDIUM | `api-` |
| 9 | Microservices | MEDIUM | `micro-` |
| 10 | DevOps & Deployment | LOW-MEDIUM | `devops-` |

## Quick Reference

### 1. Architecture (CRITICAL)

- `arch-avoid-circular-deps` - Avoid circular service provider dependencies
- `arch-feature-modules` - Organize by domain/feature, not technical layer
- `arch-single-responsibility` - Focused services over "god services"
- `arch-use-repository-pattern` - Abstract database logic for testability
- `arch-use-events` - Event-driven architecture for decoupling

### 2. Dependency Injection (CRITICAL)

- `di-avoid-service-locator` - Avoid app() helper as service locator
- `di-interface-segregation` - Interface Segregation Principle (ISP)
- `di-liskov-substitution` - Liskov Substitution Principle (LSP)
- `di-prefer-constructor-injection` - Constructor over facade/helper injection
- `di-scope-awareness` - Understand singleton/bind/scoped bindings
- `di-use-interfaces-tokens` - Bind interfaces to implementations

### 3. Error Handling (HIGH)

- `error-use-exception-handler` - Centralized exception handling
- `error-throw-http-exceptions` - Use proper HTTP exceptions
- `error-handle-queue-errors` - Handle queue and job errors properly

### 4. Security (HIGH)

- `security-auth-jwt` - Secure authentication with Sanctum/Passport
- `security-validate-all-input` - Validate with Form Requests
- `security-use-guards` - Authentication guards, gates, and policies
- `security-sanitize-output` - Prevent XSS attacks
- `security-rate-limiting` - Implement rate limiting

### 5. Performance (HIGH)

- `perf-service-provider-lifecycle` - Proper service provider boot/register lifecycle
- `perf-use-caching` - Implement caching strategies
- `perf-optimize-database` - Optimize database queries
- `perf-lazy-loading` - Lazy collections and route caching

### 6. Testing (MEDIUM-HIGH)

- `test-use-testcase-refresh-database` - Use Laravel TestCase and RefreshDatabase
- `test-e2e-http` - HTTP/feature testing with Laravel
- `test-mock-external-services` - Mock external dependencies with facades

### 7. Database & ORM (MEDIUM-HIGH)

- `db-use-transactions` - Transaction management
- `db-avoid-n-plus-one` - Avoid N+1 query problems with eager loading
- `db-use-migrations` - Use migrations for schema changes

### 8. API Design (MEDIUM)

- `api-use-dto-serialization` - API Resources and serialization
- `api-use-interceptors` - Middleware for cross-cutting concerns
- `api-versioning` - API versioning strategies
- `api-use-pipes` - Form Requests for input transformation

### 9. Microservices (MEDIUM)

- `micro-use-patterns` - Message and event patterns
- `micro-use-health-checks` - Health checks for orchestration
- `micro-use-queues` - Background job processing with queues

### 10. DevOps & Deployment (LOW-MEDIUM)

- `devops-use-config-module` - Environment configuration with config()
- `devops-use-logging` - Structured logging with channels
- `devops-graceful-shutdown` - Zero-downtime deployments

## How to Use

Read individual rule files for detailed explanations and code examples:

```
rules/arch-avoid-circular-deps.md
rules/security-validate-all-input.md
```

Each rule file contains:
- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- Additional context and references

> Only read `AGENTS.md` or individual `rules/*.md` files when you need 
> full implementation detail for a specific rule. Do not load them proactively.

## Full Compiled Document

For the complete guide with all rules expanded: `AGENTS.md`

## Laravel Boost Compatibility

If Laravel Boost is installed, the following rules are already covered 
by its core guidelines and can be skipped:

`security-validate-all-input`, `security-auth-jwt`, `db-avoid-n-plus-one`,
`db-use-migrations`, `perf-use-caching`, `test-use-testcase-refresh-database`,
`devops-use-logging`, `api-versioning`