Laravel 13 PHP Attributes 完全指南

摘要

Laravel 13 大幅扩展了 PHP 8 Attributes 的支持，新增 36 个属性，让配置更加声明式和直观。本文将全面解析 Laravel 13 中的 PHP Attributes 应用，包括：

• PHP Attributes 核心概念与语法
• Laravel 13 新增属性一览
• 控制器属性详解
• 路由属性应用
• 验证属性使用
• 自定义属性创建

本文适合希望采用声明式配置风格的 Laravel 开发者。

1. PHP Attributes 概述

1.1 什么是 PHP Attributes

PHP Attributes 是 PHP 8.0 引入的特性，允许在类、方法、属性等声明上添加结构化元数据。Laravel 13 充分利用这一特性，将传统配置方式转变为声明式风格。

1.2 传统方式 vs Attributes

// 传统方式：路由定义在 routes/web.php
Route::get('/users', [UserController::class, 'index'])
    ->middleware('auth')
    ->name('users.index');

// Laravel 13 Attributes 方式
class UserController extends Controller
{
    #[Get('/users', name: 'users.index')]
    #[Middleware('auth')]
    public function index()
    {
        // ...
    }
}

1.3 核心优势

优势	描述
配置集中	配置与代码放在一起
可读性强	一目了然的声明式风格
IDE 友好	更好的代码提示和导航
类型安全	编译时检查
减少样板代码	减少配置文件内容

2. Laravel 13 新增属性一览

2.1 控制器属性

属性	用途
#[Middleware]	定义中间件
#[Authorize]	定义授权策略
#[Route]	定义路由
#[Get]	GET 路由快捷方式
#[Post]	POST 路由快捷方式
#[Put]	PUT 路由快捷方式
#[Delete]	DELETE 路由快捷方式
#[Patch]	PATCH 路由快捷方式

2.2 队列属性

属性	用途
#[Tries]	最大尝试次数
#[Backoff]	重试间隔
#[Timeout]	超时时间
#[FailOnTimeout]	超时失败
#[MaxExceptions]	最大异常数
#[WithoutOverlapping]	防止重叠
#[ShouldBeUnique]	唯一任务

2.3 验证属性

属性	用途
#[Rule]	验证规则
#[Required]	必填验证
#[Email]	邮箱验证
#[Url]	URL 验证
#[Date]	日期验证

2.4 Eloquent 属性

属性	用途
#[ObservedBy]	观察者
#[Scope]	查询作用域
#[Accessor]	访问器
#[Mutator]	修改器

3. 控制器属性详解

3.1 中间件属性

<?php

namespace App\Http\Controllers;

use Illuminate\Routing\Attributes\Controllers\Middleware;

#[Middleware('auth')]
class UserController extends Controller
{
    #[Middleware('verified')]
    public function dashboard()
    {
        // 需要认证和邮箱验证
    }
    
    #[Middleware(['auth', 'admin'])]
    public function adminPanel()
    {
        // 需要认证和管理员权限
    }
    
    #[Middleware('throttle:60,1')]
    public function api()
    {
        // 限流：每分钟 60 次
    }
}

3.2 中间件排除

#[Middleware('auth')]
class UserController extends Controller
{
    public function index()
    {
        // 需要 auth 中间件
    }
    
    #[Middleware(except: ['auth'])]
    public function public()
    {
        // 不需要 auth 中间件
    }
}

3.3 授权属性

<?php

namespace App\Http\Controllers;

use App\Models\Post;
use Illuminate\Routing\Attributes\Controllers\Authorize;

class PostController extends Controller
{
    #[Authorize('create', Post::class)]
    public function create()
    {
        // 只有有创建权限的用户可以访问
    }
    
    #[Authorize('update', 'post')]
    public function update(Post $post)
    {
        // 自动解析 'post' 路由参数
    }
    
    #[Authorize('delete', [Post::class, 'post'])]
    public function destroy(Post $post)
    {
        // 使用路由参数解析模型
    }
}

4. 路由属性详解

4.1 基本路由

<?php

namespace App\Http\Controllers;

use Illuminate\Routing\Attributes\Get;
use Illuminate\Routing\Attributes\Post;
use Illuminate\Routing\Attributes\Put;
use Illuminate\Routing\Attributes\Delete;

class PostController extends Controller
{
    #[Get('/posts')]
    public function index()
    {
        // GET /posts
    }
    
    #[Get('/posts/{post}')]
    public function show(Post $post)
    {
        // GET /posts/{post}
    }
    
    #[Post('/posts')]
    public function store()
    {
        // POST /posts
    }
    
    #[Put('/posts/{post}')]
    public function update(Post $post)
    {
        // PUT /posts/{post}
    }
    
    #[Delete('/posts/{post}')]
    public function destroy(Post $post)
    {
        // DELETE /posts/{post}
    }
}

4.2 路由参数

#[Get('/users/{user}/posts/{post}')]
public function showUserPost(User $user, Post $post)
{
    // GET /users/{user}/posts/{post}
}

#[Get('/posts/{post:slug}')]
public function showBySlug(Post $post)
{
    // 使用 slug 字段解析
}

4.3 路由名称

#[Get('/posts', name: 'posts.index')]
public function index()
{
    // route('posts.index')
}

#[Get('/posts/{post}', name: 'posts.show')]
public function show(Post $post)
{
    // route('posts.show', $post)
}

4.4 路由组

<?php

namespace App\Http\Controllers;

use Illuminate\Routing\Attributes\Middleware;
use Illuminate\Routing\Attributes\Prefix;
use Illuminate\Routing\Attributes\Get;

#[Prefix('api/v1')]
#[Middleware(['auth:sanctum', 'throttle:api'])]
class ApiPostController extends Controller
{
    #[Get('/posts')]
    public function index()
    {
        // GET /api/v1/posts
    }
    
    #[Get('/posts/{post}')]
    public function show(Post $post)
    {
        // GET /api/v1/posts/{post}
    }
}

4.5 资源路由

<?php

namespace App\Http\Controllers;

use Illuminate\Routing\Attributes\Resource;

#[Resource('posts')]
class PostController extends Controller
{
    public function index() {}
    public function create() {}
    public function store() {}
    public function show($id) {}
    public function edit($id) {}
    public function update($id) {}
    public function destroy($id) {}
}

5. 验证属性详解

5.1 表单请求验证

<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Attributes\Rule;
use Illuminate\Validation\Attributes\Required;
use Illuminate\Validation\Attributes\Email;
use Illuminate\Validation\Attributes\Password;

class StoreUserRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'name' => ['required', 'string', 'max:255'],
            'email' => ['required', 'email', 'unique:users'],
            'password' => ['required', Password::defaults()],
        ];
    }
}

5.2 模型属性验证

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Validation\Attributes\Required;
use Illuminate\Validation\Attributes\Email;
use Illuminate\Validation\Attributes\Rule;

class User extends Model
{
    #[Required]
    #[Rule('string', 'max:255')]
    protected string $name;
    
    #[Required]
    #[Email]
    #[Rule('unique:users')]
    protected string $email;
}

6. 队列属性详解

6.1 任务配置

<?php

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\Attributes\Tries;
use Illuminate\Queue\Attributes\Backoff;
use Illuminate\Queue\Attributes\Timeout;
use Illuminate\Queue\Attributes\FailOnTimeout;

#[Tries(3)]
#[Backoff([10, 30, 60])]
#[Timeout(120)]
#[FailOnTimeout]
class ProcessPodcast implements ShouldQueue
{
    use Queueable;
    
    public function handle()
    {
        // 任务逻辑
    }
}

6.2 唯一任务

<?php

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\Attributes\ShouldBeUnique;
use Illuminate\Queue\Attributes\WithoutOverlapping;

#[ShouldBeUnique(3600)] // 1 小时内唯一
class SendWelcomeEmail implements ShouldQueue
{
    use Queueable;
    
    public function uniqueId(): string
    {
        return $this->user->id;
    }
}

#[WithoutOverlapping(10)] // 10 分钟内不重叠
class GenerateReport implements ShouldQueue
{
    use Queueable;
}

6.3 队列连接

<?php

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\Attributes\OnConnection;
use Illuminate\Queue\Attributes\OnQueue;

#[OnConnection('redis')]
#[OnQueue('podcasts')]
class ProcessPodcast implements ShouldQueue
{
    use Queueable;
}

7. Eloquent 属性详解

7.1 观察者

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Attributes\ObservedBy;
use App\Observers\UserObserver;

#[ObservedBy(UserObserver::class)]
class User extends Model
{
    // 观察者自动注册
}

7.2 查询作用域

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Attributes\Scope;

class User extends Model
{
    #[Scope]
    public function active($query)
    {
        return $query->where('active', true);
    }
    
    #[Scope]
    public function ofType($query, string $type)
    {
        return $query->where('type', $type);
    }
}

// 使用
User::active()->ofType('admin')->get();

7.3 访问器和修改器

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Casts\Attribute;
use Illuminate\Database\Eloquent\Attributes\Accessor;
use Illuminate\Database\Eloquent\Attributes\Mutator;

class User extends Model
{
    #[Accessor]
    public function fullName(): Attribute
    {
        return Attribute::make(
            get: fn($value, $attributes) => $attributes['first_name'] . ' ' . $attributes['last_name'],
        );
    }
    
    #[Mutator]
    public function password(): Attribute
    {
        return Attribute::make(
            set: fn($value) => bcrypt($value),
        );
    }
}

8. 自定义属性

8.1 创建自定义属性

<?php

namespace App\Attributes;

use Attribute;

#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]
class LogActivity
{
    public function __construct(
        public string $action,
        public string $description = '',
    ) {}
}

8.2 使用自定义属性

<?php

namespace App\Http\Controllers;

use App\Attributes\LogActivity;

class PostController extends Controller
{
    #[LogActivity('post.created', 'User created a new post')]
    public function store()
    {
        // 创建文章
    }
    
    #[LogActivity('post.deleted', 'User deleted a post')]
    public function destroy($id)
    {
        // 删除文章
    }
}

8.3 处理自定义属性

<?php

namespace App\Services;

use Illuminate\Support\Facades\Log;
use ReflectionClass;

class ActivityLogService
{
    public function log(object $controller, string $method): void
    {
        $reflection = new ReflectionClass($controller);
        $methodReflection = $reflection->getMethod($method);
        
        $attributes = $methodReflection->getAttributes(LogActivity::class);
        
        foreach ($attributes as $attribute) {
            $log = $attribute->newInstance();
            
            Log::info("Activity: {$log->action}", [
                'description' => $log->description,
                'user_id' => auth()->id(),
            ]);
        }
    }
}

9. 最佳实践

9.1 属性组织

<?php

namespace App\Http\Controllers;

use Illuminate\Routing\Attributes\Get;
use Illuminate\Routing\Attributes\Middleware;
use Illuminate\Routing\Attributes\Authorize;
use Illuminate\Routing\Attributes\Prefix;

#[Prefix('api/v1')]
#[Middleware(['auth:sanctum', 'throttle:api'])]
class PostController extends Controller
{
    #[Get('/posts')]
    #[Authorize('viewAny', Post::class)]
    public function index()
    {
        // ...
    }
}

9.2 避免过度使用

// 不推荐：过多属性
#[Get('/posts')]
#[Middleware('auth')]
#[Middleware('verified')]
#[Middleware('admin')]
#[Authorize('viewAny')]
#[Throttle(60)]
#[Cache(3600)]
public function index() {}

// 推荐：合理组合
#[Get('/posts')]
#[Middleware(['auth', 'verified', 'admin'])]
#[Authorize('viewAny')]
public function index() {}

9.3 文档注释

/**
 * 获取文章列表
 * 
 * @return \Illuminate\Http\JsonResponse
 */
#[Get('/posts', name: 'posts.index')]
#[Authorize('viewAny', Post::class)]
public function index()
{
    // ...
}

10. 总结

Laravel 13 的 PHP Attributes 支持为开发者提供了声明式配置的强大能力：

1. 配置集中：配置与代码放在一起，更易维护
2. 类型安全：编译时检查，减少错误
3. IDE 友好：更好的代码提示和导航
4. 可扩展：支持自定义属性

通过本指南，您已经掌握了 Laravel 13 PHP Attributes 的核心用法，可以开始采用声明式风格编写代码了。

参考资料

• Laravel 13 控制器文档
• Laravel 13 队列文档
• PHP 8 Attributes 文档