laravel-12（Laravel 12 前端）

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:

# 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():

// ✅ 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:

// ✅ 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:

// ✅ 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:

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

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

// ❌ 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:

php artisan make:job ProcessPodcast

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:

# 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

1. Use return type hints on relationships:

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

1. Use casts() method for type casting:

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

1. Use constructor property promotion:

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

Working with Controllers

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

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:

php artisan make:resource PostResource

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:

// ❌ 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

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

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

Best Practices Summary

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

Common Tasks Workflow

Creating a New Resource

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

Adding Authentication to Routes

1. Use middleware in route definition or bootstrap/app.php
2. Access user via $request->user()
3. Use policies for authorization
4. 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.