laravel

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Laravel Skill

Laravel 技能

Comprehensive assistance with Laravel 12.x development, including routing, Eloquent ORM, migrations, authentication, API development, and modern PHP patterns.

为Laravel 12.x开发提供全面支持，包括路由、Eloquent ORM、数据库迁移、身份验证、API开发以及现代PHP模式。

When to Use This Skill

何时使用此技能

This skill should be triggered when:

Building Laravel applications or APIs
Working with Eloquent models, relationships, and queries
Setting up authentication, authorization, or API tokens
Creating database migrations, seeders, or factories
Implementing middleware, service providers, or events
Using Laravel's built-in features (queues, cache, validation, etc.)
Troubleshooting Laravel errors or performance issues
Following Laravel best practices and conventions
Implementing RESTful APIs with Laravel Sanctum or Passport
Working with Laravel Mix, Vite, or frontend assets

在以下场景中应触发此技能：

构建Laravel应用或API
处理Eloquent模型、关联关系和查询
设置身份验证、授权或API令牌
创建数据库迁移、填充器或工厂
实现中间件、服务提供者或事件
使用Laravel的内置功能（队列、缓存、验证等）
排查Laravel错误或性能问题
遵循Laravel最佳实践和约定
使用Laravel Sanctum或Passport实现RESTful API
处理Laravel Mix、Vite或前端资源

Quick Reference

快速参考

Basic Routing

基础路由

php

// Basic routes
Route::get('/users', [UserController::class, 'index']);
Route::post('/users', [UserController::class, 'store']);

// Route parameters
Route::get('/users/{id}', function ($id) {
    return User::find($id);
});

// Named routes
Route::get('/profile', ProfileController::class)->name('profile');

// Route groups with middleware
Route::middleware(['auth'])->group(function () {
    Route::get('/dashboard', [DashboardController::class, 'index']);
    Route::resource('posts', PostController::class);
});

php

// Basic routes
Route::get('/users', [UserController::class, 'index']);
Route::post('/users', [UserController::class, 'store']);

// Route parameters
Route::get('/users/{id}', function ($id) {
    return User::find($id);
});

// Named routes
Route::get('/profile', ProfileController::class)->name('profile');

// Route groups with middleware
Route::middleware(['auth'])->group(function () {
    Route::get('/dashboard', [DashboardController::class, 'index']);
    Route::resource('posts', PostController::class);
});

Eloquent Model Basics

Eloquent 模型基础

php

// Define a model with relationships
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasMany;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

class Post extends Model
{
    protected $fillable = ['title', 'content', 'user_id'];

    protected $casts = [
        'published_at' => 'datetime',
    ];

    public function user(): BelongsTo
    {
        return $this->belongsTo(User::class);
    }

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

php

// Define a model with relationships
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasMany;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

class Post extends Model
{
    protected $fillable = ['title', 'content', 'user_id'];

    protected $casts = [
        'published_at' => 'datetime',
    ];

    public function user(): BelongsTo
    {
        return $this->belongsTo(User::class);
    }

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

Database Migrations

数据库迁移

php

// Create a migration
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('posts', function (Blueprint $table) {
            $table->id();
            $table->foreignId('user_id')->constrained()->cascadeOnDelete();
            $table->string('title');
            $table->text('content');
            $table->timestamp('published_at')->nullable();
            $table->timestamps();

            $table->index(['user_id', 'published_at']);
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('posts');
    }
};

php

// Create a migration
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('posts', function (Blueprint $table) {
            $table->id();
            $table->foreignId('user_id')->constrained()->cascadeOnDelete();
            $table->string('title');
            $table->text('content');
            $table->timestamp('published_at')->nullable();
            $table->timestamps();

            $table->index(['user_id', 'published_at']);
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('posts');
    }
};

Form Validation

表单验证

php

// Controller validation
public function store(Request $request)
{
    $validated = $request->validate([
        'title' => 'required|max:255',
        'content' => 'required',
        'email' => 'required|email|unique:users',
        'tags' => 'array|min:1',
        'tags.*' => 'string|max:50',
    ]);

    return Post::create($validated);
}

// Form Request validation
namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class StorePostRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'title' => 'required|max:255',
            'content' => 'required|min:100',
        ];
    }
}

php

// Controller validation
public function store(Request $request)
{
    $validated = $request->validate([
        'title' => 'required|max:255',
        'content' => 'required',
        'email' => 'required|email|unique:users',
        'tags' => 'array|min:1',
        'tags.*' => 'string|max:50',
    ]);

    return Post::create($validated);
}

// Form Request validation
namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class StorePostRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'title' => 'required|max:255',
            'content' => 'required|min:100',
        ];
    }
}

Eloquent Query Builder

Eloquent 查询构建器

php

// Common query patterns
// Eager loading to avoid N+1 queries
$posts = Post::with(['user', 'comments'])
    ->where('published_at', '<=', now())
    ->orderBy('published_at', 'desc')
    ->paginate(15);

// Conditional queries
$query = Post::query();

if ($request->has('search')) {
    $query->where('title', 'like', "%{$request->search}%");
}

if ($request->has('author')) {
    $query->whereHas('user', function ($q) use ($request) {
        $q->where('name', $request->author);
    });
}

$posts = $query->get();

php

// Common query patterns
// Eager loading to avoid N+1 queries
$posts = Post::with(['user', 'comments'])
    ->where('published_at', '<=', now())
    ->orderBy('published_at', 'desc')
    ->paginate(15);

// Conditional queries
$query = Post::query();

if ($request->has('search')) {
    $query->where('title', 'like', "%{$request->search}%");
}

if ($request->has('author')) {
    $query->whereHas('user', function ($q) use ($request) {
        $q->where('name', $request->author);
    });
}

$posts = $query->get();

API Resource Controllers

API 资源控制器

php

namespace App\Http\Controllers\Api;

use App\Models\Post;
use App\Http\Resources\PostResource;
use Illuminate\Http\Request;

class PostController extends Controller
{
    public function index()
    {
        return PostResource::collection(
            Post::with('user')->latest()->paginate()
        );
    }

    public function store(Request $request)
    {
        $post = Post::create($request->validated());

        return new PostResource($post);
    }

    public function show(Post $post)
    {
        return new PostResource($post->load('user', 'comments'));
    }

    public function update(Request $request, Post $post)
    {
        $post->update($request->validated());

        return new PostResource($post);
    }
}

php

namespace App\Http\Controllers\Api;

use App\Models\Post;
use App\Http\Resources\PostResource;
use Illuminate\Http\Request;

class PostController extends Controller
{
    public function index()
    {
        return PostResource::collection(
            Post::with('user')->latest()->paginate()
        );
    }

    public function store(Request $request)
    {
        $post = Post::create($request->validated());

        return new PostResource($post);
    }

    public function show(Post $post)
    {
        return new PostResource($post->load('user', 'comments'));
    }

    public function update(Request $request, Post $post)
    {
        $post->update($request->validated());

        return new PostResource($post);
    }
}

API Resources (Transformers)

API 资源（转换器）

php

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\JsonResource;

class PostResource extends JsonResource
{
    public function toArray($request): array
    {
        return [
            'id' => $this->id,
            'title' => $this->title,
            'slug' => $this->slug,
            'excerpt' => $this->excerpt,
            'content' => $this->when($request->routeIs('posts.show'), $this->content),
            'author' => new UserResource($this->whenLoaded('user')),
            'comments_count' => $this->when($this->comments_count, $this->comments_count),
            'published_at' => $this->published_at?->toISOString(),
            'created_at' => $this->created_at->toISOString(),
        ];
    }
}

php

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\JsonResource;

class PostResource extends JsonResource
{
    public function toArray($request): array
    {
        return [
            'id' => $this->id,
            'title' => $this->title,
            'slug' => $this->slug,
            'excerpt' => $this->excerpt,
            'content' => $this->when($request->routeIs('posts.show'), $this->content),
            'author' => new UserResource($this->whenLoaded('user')),
            'comments_count' => $this->when($this->comments_count, $this->comments_count),
            'published_at' => $this->published_at?->toISOString(),
            'created_at' => $this->created_at->toISOString(),
        ];
    }
}

Authentication with Sanctum

使用Sanctum进行身份验证

php

// API token authentication setup
// In config/sanctum.php - configure stateful domains

// Issue tokens
use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens;
}

// Login endpoint
public function login(Request $request)
{
    $credentials = $request->validate([
        'email' => 'required|email',
        'password' => 'required',
    ]);

    if (!Auth::attempt($credentials)) {
        return response()->json(['message' => 'Invalid credentials'], 401);
    }

    $token = $request->user()->createToken('api-token')->plainTextToken;

    return response()->json(['token' => $token]);
}

// Protect routes
Route::middleware('auth:sanctum')->group(function () {
    Route::get('/user', fn(Request $r) => $r->user());
});

php

// API token authentication setup
// In config/sanctum.php - configure stateful domains

// Issue tokens
use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens;
}

// Login endpoint
public function login(Request $request)
{
    $credentials = $request->validate([
        'email' => 'required|email',
        'password' => 'required',
    ]);

    if (!Auth::attempt($credentials)) {
        return response()->json(['message' => 'Invalid credentials'], 401);
    }

    $token = $request->user()->createToken('api-token')->plainTextToken;

    return response()->json(['token' => $token]);
}

// Protect routes
Route::middleware('auth:sanctum')->group(function () {
    Route::get('/user', fn(Request $r) => $r->user());
});

Jobs and Queues

任务与队列

php

// Create a job
namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\InteractsWithQueue;

class ProcessVideo implements ShouldQueue
{
    use InteractsWithQueue, Queueable;

    public function __construct(
        public Video $video
    ) {}

    public function handle(): void
    {
        // Process the video
        $this->video->process();
    }
}

// Dispatch jobs
ProcessVideo::dispatch($video);
ProcessVideo::dispatch($video)->onQueue('videos')->delay(now()->addMinutes(5));

php

// Create a job
namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\InteractsWithQueue;

class ProcessVideo implements ShouldQueue
{
    use InteractsWithQueue, Queueable;

    public function __construct(
        public Video $video
    ) {}

    public function handle(): void
    {
        // Process the video
        $this->video->process();
    }
}

// Dispatch jobs
ProcessVideo::dispatch($video);
ProcessVideo::dispatch($video)->onQueue('videos')->delay(now()->addMinutes(5));

Service Container and Dependency Injection

服务容器与依赖注入

php

// Bind services in AppServiceProvider
use App\Services\PaymentService;

public function register(): void
{
    $this->app->singleton(PaymentService::class, function ($app) {
        return new PaymentService(
            config('services.stripe.secret')
        );
    });
}

// Use dependency injection in controllers
public function __construct(
    protected PaymentService $payment
) {}

public function charge(Request $request)
{
    return $this->payment->charge(
        $request->user(),
        $request->amount
    );
}

php

// Bind services in AppServiceProvider
use App\Services\PaymentService;

public function register(): void
{
    $this->app->singleton(PaymentService::class, function ($app) {
        return new PaymentService(
            config('services.stripe.secret')
        );
    });
}

// Use dependency injection in controllers
public function __construct(
    protected PaymentService $payment
) {}

public function charge(Request $request)
{
    return $this->payment->charge(
        $request->user(),
        $request->amount
    );
}

Reference Files

参考文件

This skill includes comprehensive documentation in

references/

other.md - Laravel 12.x installation guide and core documentation

Use the reference files for detailed information about:

Installation and configuration
Framework architecture and concepts
Advanced features and packages
Deployment and optimization

此技能在

references/

目录中包含全面文档：

other.md - Laravel 12.x安装指南及核心文档

使用参考文件获取以下方面的详细信息：

安装与配置
框架架构与概念
高级功能与扩展包
部署与优化

Key Concepts

核心概念

MVC Architecture

MVC架构

Laravel follows the Model-View-Controller pattern:

Models: Eloquent ORM classes representing database tables
Views: Blade templates for rendering HTML
Controllers: Handle HTTP requests and return responses

Laravel遵循模型-视图-控制器模式：

模型：代表数据库表的Eloquent ORM类
视图：用于渲染HTML的Blade模板
控制器：处理HTTP请求并返回响应

Eloquent ORM

Laravel's powerful database abstraction layer:

Active Record pattern: Each model instance represents a database row
Relationships: belongsTo, hasMany, belongsToMany, morphMany, etc.
Query Builder: Fluent interface for building SQL queries
Eager Loading: Prevent N+1 query problems with
```
with()
```

Laravel强大的数据库抽象层：

活动记录模式：每个模型实例代表一行数据库记录
关联关系：belongsTo、hasMany、belongsToMany、morphMany等
查询构建器：用于构建SQL查询的流畅接口
预加载：使用
```
with()
```
避免N+1查询问题

Routing

路由

Define application endpoints:

Route methods: get, post, put, patch, delete
Route parameters: Required
```
{id}
```
and optional
```
{id?}
```
Route groups: Share middleware, prefixes, namespaces
Resource routes: Auto-generate RESTful routes

定义应用端点：

路由方法：get、post、put、patch、delete
路由参数：必填
```
{id}
```
和可选
```
{id?}
```
路由组：共享中间件、前缀、命名空间
资源路由：自动生成RESTful路由

Middleware

中间件

Filter HTTP requests:

Built-in: auth, throttle, verified, signed
Custom: Create your own request/response filters
Global: Apply to all routes
Route-specific: Apply to specific routes or groups

过滤HTTP请求：

内置中间件：auth、throttle、verified、signed
自定义中间件：创建自己的请求/响应过滤器
全局中间件：应用于所有路由
路由专属中间件：应用于特定路由或路由组

Service Container

服务容器

Laravel's dependency injection container:

Automatic resolution: Type-hint dependencies in constructors
Binding: Register class implementations
Singletons: Share single instance across requests

Laravel的依赖注入容器：

自动解析：在构造函数中通过类型提示依赖
绑定：注册类的实现
单例：在请求间共享单个实例

Artisan Commands

Artisan命令

Laravel's CLI tool:

bash

php artisan make:model Post -mcr  # Create model, migration, controller, resource
php artisan migrate               # Run migrations
php artisan db:seed              # Seed database
php artisan queue:work           # Process queue jobs
php artisan optimize:clear       # Clear all caches

Laravel的CLI工具：

bash

php artisan make:model Post -mcr  # 创建模型、迁移、控制器、资源
php artisan migrate               # 运行迁移
php artisan db:seed              # 填充数据库
php artisan queue:work           # 处理队列任务
php artisan optimize:clear       # 清除所有缓存

Working with This Skill

使用此技能的指南

For Beginners

面向初学者

Start with:

Installation: Set up Laravel using Composer
Routing: Learn basic route definitions in
```
routes/web.php
```
Controllers: Create controllers with
```
php artisan make:controller
```
Models: Understand Eloquent basics and relationships
Migrations: Define database schema with migrations
Blade Templates: Create views with Laravel's templating engine

从以下内容开始：

安装：使用Composer搭建Laravel环境
路由：学习
```
routes/web.php
```
中的基础路由定义
控制器：使用
```
php artisan make:controller
```
创建控制器
模型：理解Eloquent基础和关联关系
迁移：使用迁移定义数据库架构
Blade模板：使用Laravel的模板引擎创建视图

For Intermediate Users

面向中级用户

Focus on:

Form Requests: Validation and authorization in dedicated classes
API Resources: Transform models for JSON responses
Authentication: Implement with Laravel Breeze or Sanctum
Relationships: Master eager loading and complex relationships
Queues: Offload time-consuming tasks to background jobs
Events & Listeners: Decouple application logic

重点关注：

表单请求：在专用类中处理验证和授权
API资源：为JSON响应转换模型数据
身份验证：使用Laravel Breeze或Sanctum实现
关联关系：掌握预加载和复杂关联
队列：将耗时任务卸载到后台作业
事件与监听器：解耦应用逻辑

For Advanced Users

面向高级用户

Explore:

Service Providers: Register application services
Custom Middleware: Create reusable request filters
Package Development: Build reusable Laravel packages
Testing: Write feature and unit tests with PHPUnit
Performance: Optimize queries, caching, and response times
Deployment: CI/CD pipelines and production optimization

探索以下内容：

服务提供者：注册应用服务
自定义中间件：创建可重用的请求过滤器
扩展包开发：构建可重用的Laravel扩展包
测试：使用PHPUnit编写功能和单元测试
性能优化：优化查询、缓存和响应时间
部署：CI/CD流水线与生产环境优化

Navigation Tips

导航技巧

Check Quick Reference for common code patterns
Reference the official docs at https://laravel.com/docs/12.x
Use
```
php artisan route:list
```
to view all registered routes
Use
```
php artisan tinker
```
for interactive debugging
Enable query logging to debug database performance

查看快速参考获取常见代码模式
参考官方文档：https://laravel.com/docs/12.x
使用
```
php artisan route:list
```
查看所有已注册路由
使用
```
php artisan tinker
```
进行交互式调试
启用查询日志以调试数据库性能

Common Patterns

常见模式

Repository Pattern

仓库模式

php

interface PostRepositoryInterface
{
    public function all();
    public function find(int $id);
    public function create(array $data);
}

class PostRepository implements PostRepositoryInterface
{
    public function all()
    {
        return Post::with('user')->latest()->get();
    }

    public function find(int $id)
    {
        return Post::with('user', 'comments')->findOrFail($id);
    }
}

php

interface PostRepositoryInterface
{
    public function all();
    public function find(int $id);
    public function create(array $data);
}

class PostRepository implements PostRepositoryInterface
{
    public function all()
    {
        return Post::with('user')->latest()->get();
    }

    public function find(int $id)
    {
        return Post::with('user', 'comments')->findOrFail($id);
    }
}

Action Classes (Single Responsibility)

动作类（单一职责）

php

class CreatePost
{
    public function execute(array $data): Post
    {
        return DB::transaction(function () use ($data) {
            $post = Post::create($data);
            $post->tags()->attach($data['tag_ids']);
            event(new PostCreated($post));
            return $post;
        });
    }
}

php

class CreatePost
{
    public function execute(array $data): Post
    {
        return DB::transaction(function () use ($data) {
            $post = Post::create($data);
            $post->tags()->attach($data['tag_ids']);
            event(new PostCreated($post));
            return $post;
        });
    }
}

Query Scopes

查询作用域

php

class Post extends Model
{
    public function scopePublished($query)
    {
        return $query->where('published_at', '<=', now());
    }

    public function scopeByAuthor($query, User $user)
    {
        return $query->where('user_id', $user->id);
    }
}

// Usage
Post::published()->byAuthor($user)->get();

php

class Post extends Model
{
    public function scopePublished($query)
    {
        return $query->where('published_at', '<=', now());
    }

    public function scopeByAuthor($query, User $user)
    {
        return $query->where('user_id', $user->id);
    }
}

// Usage
Post::published()->byAuthor($user)->get();

Resources

资源

Official Documentation

官方文档

Laravel Docs: https://laravel.com/docs/12.x
API Reference: https://laravel.com/api/12.x
Laracasts: https://laracasts.com (video tutorials)

Community

社区资源

Laravel News: https://laravel-news.com
Laravel Forums: https://laracasts.com/discuss
GitHub: https://github.com/laravel/laravel

Laravel新闻：https://laravel-news.com
Laravel论坛：https://laracasts.com/discuss
GitHub：https://github.com/laravel/laravel

Tools

工具

Laravel Telescope: Debugging and monitoring
Laravel Horizon: Queue monitoring
Laravel Debugbar: Development debugging
Laravel IDE Helper: IDE autocompletion

Laravel Telescope：调试与监控
Laravel Horizon：队列监控
Laravel Debugbar：开发调试
Laravel IDE Helper：IDE自动补全

Best Practices

最佳实践

Use Form Requests: Separate validation logic from controllers
Eager Load Relationships: Avoid N+1 query problems
Use Resource Controllers: Follow RESTful conventions
Type Hints: Leverage PHP type declarations for better IDE support
Database Transactions: Wrap related database operations
Queue Jobs: Offload slow operations to background workers
Cache Queries: Cache expensive database queries
API Resources: Transform data consistently for APIs
Events: Decouple application logic with events and listeners
Tests: Write tests for critical application logic

使用表单请求：将验证逻辑与控制器分离
预加载关联关系：避免N+1查询问题
使用资源控制器：遵循RESTful规范
类型提示：利用PHP类型声明提升IDE支持
数据库事务：包裹相关数据库操作
队列任务：将慢操作卸载到后台 worker
缓存查询：缓存昂贵的数据库查询
API资源：为API提供一致的数据转换
事件：使用事件和监听器解耦应用逻辑
测试：为关键应用逻辑编写测试

Notes

注意事项

Laravel 12.x requires PHP 8.2 or higher
Uses Composer for dependency management
Includes Vite for asset compilation (replaces Laravel Mix)
Supports multiple database systems (MySQL, PostgreSQL, SQLite, SQL Server)
Built-in support for queues, cache, sessions, and file storage
Excellent ecosystem with first-party packages (Sanctum, Horizon, Telescope, etc.)

Laravel 12.x需要PHP 8.2或更高版本
使用Composer进行依赖管理
使用Vite进行资源编译（替代Laravel Mix）
支持多种数据库系统（MySQL、PostgreSQL、SQLite、SQL Server）
内置队列、缓存、会话和文件存储支持
拥有完善的生态系统，包含官方扩展包（Sanctum、Horizon、Telescope等）