Laravel 12 Best Practices
Comprehensive best practices guide for Laravel 12 applications. Contains 45+ rules across 8 categories for building scalable, maintainable Laravel applications.
When to Apply
Reference these guidelines when:
Creating controllers, models, and services Writing migrations and database queries Implementing validation and form requests Building APIs with Laravel Structuring Laravel applications Rule Categories by Priority Priority Category Impact Prefix 1 Architecture & Structure CRITICAL arch- 2 Eloquent & Database CRITICAL eloquent- 3 Controllers & Routing HIGH controller-, ctrl- 4 Validation & Requests HIGH validation-, valid- 5 Security HIGH sec- 6 Performance MEDIUM perf- 7 API Design MEDIUM api- Quick Reference 1. Architecture & Structure (CRITICAL) arch-service-classes - Extract business logic to services arch-action-classes - Single-purpose action classes arch-repository-pattern - When to use repositories arch-dto-pattern - Data transfer objects arch-value-objects - Encapsulate domain concepts arch-event-driven - Decouple with events and listeners arch-feature-folders - Organize by domain/feature 2. Eloquent & Database (CRITICAL) eloquent-eager-loading - Prevent N+1 queries eloquent-chunking - Process large datasets eloquent-query-scopes - Reusable query logic eloquent-model-events - Use observers for side effects eloquent-relationships - Define relationships properly eloquent-casts - Automatic attribute casting eloquent-accessors-mutators - Transform attributes eloquent-soft-deletes - Safe deletion with recovery eloquent-pruning - Automatic cleanup of old records 3. Controllers & Routing (HIGH) ctrl-resource-controllers - Use resource controllers controller-single-action - Single action invokable controllers controller-resource-methods - RESTful resource methods controller-form-requests - Use form requests controller-api-resources - Transform API responses controller-middleware - Apply middleware properly controller-dependency-injection - Inject dependencies 4. Validation & Requests (HIGH) validation-form-requests - Use form request classes validation-custom-rules - Create custom rules validation-conditional-rules - Conditional validation validation-array-validation - Validate nested arrays validation-after-hooks - Complex validation logic 5. Security (HIGH) sec-mass-assignment - Protect against mass assignment Additional security rules can be added as needed 6. Performance (MEDIUM) Performance rules can be added for caching, queues, and optimization 7. API Design (MEDIUM) API design rules can be added for versioning and response formatting Essential Patterns Controller with Form Request
validated(); $post = Post::create($validated); return redirect() ->route('posts.show', $post) ->with('success', 'Post created successfully.'); } public function update(UpdatePostRequest $request, Post $post): RedirectResponse { $post->update($request->validated()); return redirect() ->route('posts.show', $post) ->with('success', 'Post updated successfully.'); } } Form Request Class user()->can('create', Post::class); } public function rules(): array { return [ 'title' => ['required', 'string', 'max:255'], 'body' => ['required', 'string', 'min:100'], 'category_id' => ['required', 'exists:categories,id'], 'tags' => ['nullable', 'array'], 'tags.*' => ['exists:tags,id'], 'published_at' => ['nullable', 'date', 'after:now'], ]; } public function messages(): array { return [ 'body.min' => 'The post body must be at least 100 characters.', ]; } } Service Class Pattern update([ 'published_at' => now(), 'status' => 'published', ]); event(new PostPublished($post)); $this->notifications->notifyFollowers($post->author, $post); return $post->fresh(); }); } } Eloquent Model 'datetime', ]; // Relationships public function author(): BelongsTo { return $this->belongsTo(User::class, 'user_id'); } public function category(): BelongsTo { return $this->belongsTo(Category::class); } public function tags(): BelongsToMany { return $this->belongsToMany(Tag::class)->withTimestamps(); } // Scopes public function scopePublished(Builder $query): Builder { return $query->whereNotNull('published_at') ->where('published_at', '<=', now()); } public function scopeByCategory(Builder $query, int $categoryId): Builder { return $query->where('category_id', $categoryId); } // Accessors & Mutators protected function title(): Attribute { return Attribute::make( set: fn (string $value) => ucfirst($value), ); } } Migration Best Practices id(); $table->foreignId('user_id')->constrained()->cascadeOnDelete(); $table->foreignId('category_id')->constrained()->cascadeOnDelete(); $table->string('title'); $table->string('slug')->unique(); $table->text('body'); $table->timestamp('published_at')->nullable(); $table->timestamps(); // Indexes for common queries $table->index(['user_id', 'published_at']); $table->index('category_id'); }); } public function down(): void { Schema::dropIfExists('posts'); } }; Eager Loading // ❌ N+1 Problem $posts = Post::all(); foreach ($posts as $post) { echo $post->author->name; // Query per post } // ✅ Eager loading $posts = Post::with(['author', 'category', 'tags'])->get(); foreach ($posts as $post) { echo $post->author->name; // No additional queries } // ✅ Nested eager loading $posts = Post::with([ 'author.profile', 'comments.user', 'tags', ])->get(); // ✅ Constrained eager loading $posts = Post::with([ 'comments' => fn ($query) => $query->latest()->limit(5), ])->get(); How to Use Read individual rule files for detailed explanations and code examples: rules/arch-service-classes.md rules/eloquent-eager-loading.md rules/validation-form-requests.md rules/_sections.md Each rule file contains: YAML frontmatter with metadata (title, impact, tags) Brief explanation of why it matters Incorrect code example with explanation Correct code example with explanation Laravel 12 and PHP 8.5 specific context and references Full Compiled Document For the complete guide with all rules expanded: AGENTS.md ?>