Laravel 12 Development Skill

This skill provides comprehensive guidance for developing high-quality Laravel 12 applications using modern best practices, proper architecture patterns, and Laravel's streamlined structure.

Purpose

Provide expert-level Laravel 12 development guidance covering:

•Modern Laravel 12 streamlined architecture and file structure
•Eloquent ORM patterns with proper type hints and relationships
•Authentication and authorization using current best practices
•Form validation with Form Request classes
•Queue and job management for background processing
•Database migrations, models, and API development
•Testing patterns and conventions
•Configuration and environment management

When to Use

Use this skill when:

•Creating or working with Laravel 12 applications
•Building models, controllers, migrations, or any Laravel components
•Implementing authentication or authorization
•Creating APIs with Eloquent resources
•Writing database queries or working with relationships
•Setting up queues and background jobs
•Writing form validation
•Configuring Laravel applications
•Following Laravel best practices and conventions
•Ensuring proper Laravel 12 structure compliance

Core Principles

1. Use Artisan Commands

Always create files using php artisan make: commands with appropriate options:

bash

# Models with migrations, factories, seeders
php artisan make:model Post -mfs

# Form Requests for validation
php artisan make:request StorePostRequest

# Controllers
php artisan make:controller PostController --resource

# Jobs
php artisan make:job ProcessPodcast

# Generic PHP classes
php artisan make:class Services/PaymentService

Important: Pass --no-interaction when running commands programmatically.

2. Follow Laravel 12 Streamlined Structure

Laravel 12 uses a simplified structure:

•No app/Http/Middleware/ directory - register middleware in bootstrap/app.php
•No app/Console/Kernel.php - use bootstrap/app.php or routes/console.php
•Commands auto-register from app/Console/Commands/
•Central configuration in bootstrap/app.php for middleware, routing, exceptions

Read references/structure.md for complete details on Laravel 12 architecture.

3. Authentication: Always Use $request->user()

CRITICAL: Always retrieve authenticated user via $request->user(), never use auth()->user() or Auth::user():

php

// ✅ CORRECT
public function index(Request $request): Response
{
    $user = $request->user();
    // ...
}

// ❌ WRONG
public function index(): Response
{
    $user = auth()->user();  // Don't do this
}

Read references/authentication.md for complete authentication and authorization guidance.

4. Database: Eloquent Over DB Facade

Prefer Eloquent models and relationships over raw queries:

php

// ✅ PREFER
$users = User::query()->where('active', true)->get();

// ❌ AVOID
$users = DB::table('users')->where('active', true)->get();

Prevent N+1 queries by eager loading relationships:

php

// ✅ GOOD - Prevents N+1
$posts = Post::with('user', 'comments')->get();

// ❌ BAD - Causes N+1
$posts = Post::all();
foreach ($posts as $post) {
    echo $post->user->name; // New query each iteration
}

Read references/database.md for Eloquent patterns, relationships, migrations, and query optimization.

5. Validation: Always Use Form Requests

Never use inline validation. Always create Form Request classes:

bash

php artisan make:request StorePostRequest

Form Requests should include:

•Validation rules (check project conventions for array vs string format)
•Custom error messages
•Authorization logic when needed

php

public function rules(): array
{
    return [
        'title' => ['required', 'string', 'max:255'],
        'body' => ['required', 'string'],
    ];
}

Read references/validation.md for complete validation patterns and examples.

6. Configuration: Never Use env() Outside Config Files

php

// ❌ WRONG
$apiKey = env('API_KEY');

// ✅ CORRECT
$apiKey = config('services.api.key');

Environment variables should only be accessed in config/*.php files, then accessed via config() helper throughout the application.

7. Background Processing: Use Queues

Use queued jobs with ShouldQueue interface for time-consuming operations:

bash

php artisan make:job ProcessPodcast

php

class ProcessPodcast implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
    
    public int $tries = 3;
    public int $timeout = 120;
    
    public function __construct(public Podcast $podcast) {}
    
    public function handle(): void
    {
        $this->podcast->process();
    }
}

Read references/queues.md for queue patterns, job chains, batches, and worker management.

Working with Models

Model Creation

When creating models, use appropriate flags:

bash

# Model with migration, factory, seeder
php artisan make:model Post -mfs

# Model with migration, factory, seeder, policy, controller
php artisan make:model Post -mfsc --policy

Model Conventions

•Use return type hints on relationships:

php

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

•Use casts() method for type casting:

php

protected function casts(): array
{
    return [
        'published_at' => 'datetime',
        'is_featured' => 'boolean',
        'metadata' => 'array',
    ];
}

•Use constructor property promotion:

php

public function __construct(
    public string $name,
    public int $age,
) {}

Working with Controllers

•Type-hint Request in controller methods
•Use resource controllers for CRUD operations
•Return proper response types with type hints
•Use Form Requests for validation
•Keep controllers thin - move business logic to services/actions

php

public function store(StorePostRequest $request): RedirectResponse
{
    $post = Post::create($request->validated());
    
    return redirect()->route('posts.show', $post);
}

API Development

Use Eloquent API Resources for consistent API responses:

bash

php artisan make:resource PostResource

php

class PostResource extends JsonResource
{
    public function toArray($request): array
    {
        return [
            'id' => $this->id,
            'title' => $this->title,
            'author' => new UserResource($this->whenLoaded('user')),
        ];
    }
}

Migrations

CRITICAL: When modifying columns, include ALL previous attributes or they will be lost:

php

// ❌ WRONG - Loses 'nullable' attribute
$table->string('email')->unique()->change();

// ✅ CORRECT - Preserves all attributes
$table->string('email')->nullable()->unique()->change();

Reference Files

This skill includes detailed reference files for specific topics:

•references/structure.md - Laravel 12 file structure, Artisan commands, configuration
•references/authentication.md - Authentication, authorization, policies, gates
•references/database.md - Eloquent, relationships, migrations, queries, API resources
•references/validation.md - Form Requests, validation rules, custom messages
•references/queues.md - Jobs, queues, workers, chains, batches

Read the appropriate reference file(s) when working on related tasks to ensure following best practices.

PHP Conventions

•Always use curly braces for control structures, even single-line
•Use explicit return type declarations for all methods
•Use PHP 8+ constructor property promotion
•Use type hints for method parameters
•Prefer PHPDoc blocks over inline comments

php

protected function isAccessible(User $user, ?string $path = null): bool
{
    // Implementation
}

Best Practices Summary

•✅ Use php artisan make: commands to create files
•✅ Follow Laravel 12 streamlined structure
•✅ Always use $request->user() for authentication
•✅ Prefer Eloquent over DB facade
•✅ Always create Form Request classes for validation
•✅ Never use env() outside config files
•✅ Use queues for time-consuming operations
•✅ Add return type hints on relationships
•✅ Eager load to prevent N+1 queries
•✅ Include all attributes when modifying columns
•✅ Use named routes with route() helper
•✅ Use API Resources for APIs
•✅ Keep controllers thin
•✅ Write descriptive, type-safe code

Common Tasks Workflow

Creating a New Resource

•Create model with migrations and factory: php artisan make:model Post -mf
•Create Form Requests: php artisan make:request StorePostRequest
•Create controller: php artisan make:controller PostController --resource
•Create API resource (if needed): php artisan make:resource PostResource
•Define routes in appropriate routes file with named routes
•Write tests for all functionality

Adding Authentication to Routes

•Use middleware in route definition or bootstrap/app.php
•Access user via $request->user()
•Use policies for authorization
•Return appropriate responses for unauthorized access

This skill ensures Laravel applications follow modern best practices, maintain clean architecture, and leverage Laravel 12's streamlined structure effectively.