PHP Attributes - Knowledge of Laravel

什麼是 PHP Attributes

PHP Attributes 是 PHP 8.0 導入的原生 metadata 語法。可對類別、方法、屬性、函式等以 #[AttributeName] 形式加註元資訊。 Laravel 於框架本體積極採用 PHP Attributes，可以宣告式撰寫 Job 或 Eloquent 模型的設定。於 Laravel 13（v13.2.0）中，Queue attribute 可接受 enum。相較於傳統的類別屬性或方法覆寫，使用 attribute 可寫出更易讀且簡潔的程式碼。

// 傳統寫法
class ProcessOrder implements ShouldQueue
{
    public string $queue = 'orders';
    public string $connection = 'redis';
    public int $tries = 3;
    public array $backoff = [30, 60, 120];
}

// 使用 attribute 的寫法
#[Queue('orders')]
#[Connection('redis')]
#[Tries(3)]
#[Backoff(30, 60, 120)]
class ProcessOrder implements ShouldQueue
{
}

Attributes 於 PHP 8.0 以後可使用。Laravel 13 要求 PHP 8.3 以上，因此所有環境皆可使用 attribute。

Queue 相關 Attributes

Queue Job 相關的 attributes 皆位於 Illuminate\Queue\Attributes 命名空間。

`#[Queue]` — 指定 Queue 名稱

指定 Job 送往的預設 Queue 名稱。

use Illuminate\Queue\Attributes\Queue;

#[Queue('emails')]
class SendWelcomeEmail implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function handle(): void
    {
        // ...
    }
}

自 v13.2.0 起，可傳入 enum 代替字串。

enum QueueName: string
{
    case Emails = 'emails';
    case Orders = 'orders';
    case Notifications = 'notifications';
}

#[Queue(QueueName::Emails)]
class SendWelcomeEmail implements ShouldQueue
{
    // ...
}

#[Queue] attribute 的 target 被設為 Attribute::TARGET_CLASS，因此只能套用於類別。

`#[Connection]` — 指定 Connection

指定 Job 使用的預設 Queue Connection。

use Illuminate\Queue\Attributes\Connection;

#[Connection('sqs')]
class ProcessPayment implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function handle(): void
    {
        // ...
    }
}

此處也可使用 enum。

enum QueueConnection: string
{
    case Redis = 'redis';
    case Sqs = 'sqs';
    case Database = 'database';
}

#[Connection(QueueConnection::Sqs)]
class ProcessPayment implements ShouldQueue
{
    // ...
}

`#[Backoff]` — 指定重試 backoff 時間

指定 Job 失敗時，重試前的等待時間（秒）。傳入多個值時，每次重試可設定不同的等待時間（可變長引數支援）。

use Illuminate\Queue\Attributes\Backoff;

// 固定的等待時間（所有重試共通等待 60 秒）
#[Backoff(60)]
class SendEmail implements ShouldQueue
{
    // ...
}

// 各次重試不同的等待時間（指數 backoff）
#[Backoff(30, 60, 120)]
class ProcessOrder implements ShouldQueue
{
    // ...
}

觀察 Backoff 類別的實作，設計為接受可變長引數。

// Illuminate\Queue\Attributes\Backoff 的實作
#[Attribute(Attribute::TARGET_CLASS)]
class Backoff
{
    public array|int $backoff;

    public function __construct(array|int ...$backoff)
    {
        $this->backoff = count($backoff) === 1 ? $backoff[0] : $backoff;
    }
}

單一值時作為 int 存放，多個值時作為 array 存放。

`#[Tries]` — 指定重試次數

指定 Job 失敗時的最大重試次數。

use Illuminate\Queue\Attributes\Tries;

#[Tries(5)]
class ProcessPayment implements ShouldQueue
{
    // ...
}

`#[Timeout]` — 指定 Timeout

指定 Job 的最大執行時間（秒）。超過此時間時，Job 會被強制中止。

use Illuminate\Queue\Attributes\Timeout;

#[Timeout(120)]
class GenerateReport implements ShouldQueue
{
    // ...
}

`#[MaxExceptions]` — 指定容許例外次數

當發生指定次數以上的例外時，將 Job 視為失敗。搭配 #[Tries] 使用。

use Illuminate\Queue\Attributes\MaxExceptions;
use Illuminate\Queue\Attributes\Tries;

#[Tries(10)]
#[MaxExceptions(3)]
class ProcessWebhook implements ShouldQueue
{
    // ...
}

`#[UniqueFor]` — 指定唯一期間

指定防止 Job 重複執行的 lock 期間（秒）。搭配 ShouldBeUnique 使用。

use Illuminate\Contracts\Queue\ShouldBeUnique;
use Illuminate\Queue\Attributes\UniqueFor;

#[UniqueFor(3600)]
class SyncUserData implements ShouldQueue, ShouldBeUnique
{
    // ...
}

`#[DeleteWhenMissingModels]` — 模型不存在時刪除

當 Job 相依的 Eloquent 模型找不到時，將 Job 視為刪除（跳過）而非失敗。

use Illuminate\Queue\Attributes\DeleteWhenMissingModels;

#[DeleteWhenMissingModels]
class SendOrderConfirmation implements ShouldQueue
{
    public function __construct(
        protected Order $order,
    ) {}

    public function handle(): void
    {
        // 若 $order 不存在，此 Job 會被刪除
    }
}

`#[WithoutRelations]` — 排除關聯

於 Job 序列化時不將模型的關聯納入。可精簡送往 Queue 的資料量。

use Illuminate\Queue\Attributes\WithoutRelations;

#[WithoutRelations]
class ExportUser implements ShouldQueue
{
    public function __construct(
        protected User $user,
    ) {}
}

`#[FailOnTimeout]` — Timeout 時視為失敗

當發生 Timeout 時，將 Job 記錄為失敗（預設 Timeout 不會被記錄為失敗）。

use Illuminate\Queue\Attributes\FailOnTimeout;
use Illuminate\Queue\Attributes\Timeout;

#[Timeout(30)]
#[FailOnTimeout]
class ProcessLongTask implements ShouldQueue
{
    // ...
}

組合多個 Queue Attributes

可以組合這些 attribute，宣告式設定 Job 的行為。

use Illuminate\Queue\Attributes\Backoff;
use Illuminate\Queue\Attributes\Connection;
use Illuminate\Queue\Attributes\DeleteWhenMissingModels;
use Illuminate\Queue\Attributes\FailOnTimeout;
use Illuminate\Queue\Attributes\MaxExceptions;
use Illuminate\Queue\Attributes\Queue;
use Illuminate\Queue\Attributes\Timeout;
use Illuminate\Queue\Attributes\Tries;

#[Queue('payments')]
#[Connection('redis')]
#[Tries(3)]
#[Backoff(30, 60, 120)]
#[Timeout(60)]
#[MaxExceptions(2)]
#[DeleteWhenMissingModels]
class ProcessPayment implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(
        protected Order $order,
    ) {}

    public function handle(PaymentService $payment): void
    {
        $payment->charge($this->order);
    }
}

Eloquent 相關 Attributes

Eloquent 模型的 attributes 位於 Illuminate\Database\Eloquent\Attributes 命名空間。Laravel 13 新增了大量 attribute。

`#[ScopedBy]` — 指定 Global Scope

以 attribute 指定要自動套用至模型的 Global Scope 類別。支援繼承，並具有 IS_REPEATABLE 旗標，可指定多個 Scope。

use Illuminate\Database\Eloquent\Attributes\ScopedBy;

#[ScopedBy(ActiveScope::class)]
class User extends Model
{
    // 不再需要於 booted() 註冊 Scope
}

要套用多個 Scope，重複標註 attribute 或以陣列傳入。

// 重複指定（IS_REPEATABLE 對應）
#[ScopedBy(ActiveScope::class)]
#[ScopedBy(VerifiedScope::class)]
class User extends Model
{
}

// 以陣列一次指定
#[ScopedBy([ActiveScope::class, VerifiedScope::class])]
class User extends Model
{
}

與傳統 booted() 方法的比較。

// 傳統寫法
class User extends Model
{
    protected static function booted(): void
    {
        static::addGlobalScope(new ActiveScope);
        static::addGlobalScope(new VerifiedScope);
    }
}

`#[ObservedBy]` — 指定 Observer

以 attribute 指定關聯至模型的 Observer 類別。與 ScopedBy 同樣為 IS_REPEATABLE。

use Illuminate\Database\Eloquent\Attributes\ObservedBy;

#[ObservedBy(UserObserver::class)]
class User extends Model
{
}

也可指定多個 Observer。

#[ObservedBy(UserObserver::class)]
#[ObservedBy(AuditObserver::class)]
class User extends Model
{
}

不再需於傳統的 AppServiceProvider 註冊。

// 傳統寫法（AppServiceProvider）
public function boot(): void
{
    User::observe(UserObserver::class);
}

`#[UseEloquentBuilder]` — 指定自訂 Query Builder

以 attribute 指定模型所使用的自訂 Eloquent Builder。

use Illuminate\Database\Eloquent\Attributes\UseEloquentBuilder;

#[UseEloquentBuilder(UserQueryBuilder::class)]
class User extends Model
{
}

namespace App\Builders;

use Illuminate\Database\Eloquent\Builder;

class UserQueryBuilder extends Builder
{
    public function active(): static
    {
        return $this->where('active', true);
    }

    public function verified(): static
    {
        return $this->whereNotNull('email_verified_at');
    }
}

// 使用範例（可型別安全地呼叫自訂方法）
$users = User::query()->active()->verified()->get();

`#[CollectedBy]` — 指定自訂 Collection

以 attribute 指定模型的 Collection 所使用的自訂 Collection 類別。

use Illuminate\Database\Eloquent\Attributes\CollectedBy;

#[CollectedBy(UserCollection::class)]
class User extends Model
{
}

namespace App\Collections;

use Illuminate\Database\Eloquent\Collection;

class UserCollection extends Collection
{
    public function admins(): static
    {
        return $this->filter(fn (User $user) => $user->is_admin);
    }

    public function active(): static
    {
        return $this->filter(fn (User $user) => $user->active);
    }
}

`#[Table]` — 一次指定 Table 相關設定

可以一個 attribute 一次指定表格名稱、主鍵、時間戳記等多個 Table 相關設定。

use Illuminate\Database\Eloquent\Attributes\Table;

#[Table(name: 'system_users', key: 'user_id', timestamps: false)]
class SystemUser extends Model
{
}

Table attribute 可設定的選項如下。

參數	對應屬性	說明
`name`	`$table`	表格名稱
`key`	`$primaryKey`	主鍵欄位名稱
`keyType`	`$keyType`	主鍵的型別（`'int'`, `'string'` 等）
`incrementing`	`$incrementing`	主鍵的自動遞增
`timestamps`	`$timestamps`	時間戳記啟用/停用
`dateFormat`	`$dateFormat`	日期格式

`#[Scope]` — 將方法定義為本地 Scope

可將不含 scope 前綴的方法定義為 Eloquent 的本地 Scope。

use Illuminate\Database\Eloquent\Attributes\Scope;

class User extends Model
{
    #[Scope]
    public function active(Builder $query): void
    {
        $query->where('active', true);
    }

    #[Scope]
    public function verified(Builder $query): void
    {
        $query->whereNotNull('email_verified_at');
    }
}

// 傳統上方法名稱需加上「scope」前綴
// public function scopeActive(Builder $query): void

// 使用 attribute 後，方法名稱直接就是 Scope 名稱
User::query()->active()->verified()->get();

`#[UseFactory]` — 指定 Factory 類別

以 attribute 指定模型所使用的自訂 Factory 類別。

use Illuminate\Database\Eloquent\Attributes\UseFactory;

#[UseFactory(UserFactory::class)]
class User extends Model
{
}

其他 Eloquent Attributes

Attribute	說明
`#[Fillable(...$attributes)]`	指定允許批次指派的欄位
`#[Guarded(...$attributes)]`	指定於批次指派中保護的欄位
`#[Unguarded]`	停用批次指派的保護
`#[Hidden(...$attributes)]`	指定序列化時排除的欄位
`#[Visible(...$attributes)]`	指定序列化時納入的欄位
`#[Appends(...$attributes)]`	指定序列化時追加的 accessor
`#[Touches(...$relations)]`	指定更新時更新 `updated_at` 的關聯
`#[WithoutTimestamps]`	停用時間戳記
`#[WithoutIncrementing]`	停用主鍵的自動遞增
`#[DateFormat(format: '...')]`	指定日期格式
`#[UsePolicy(policyClass: '...')]`	指定關聯的 Policy 類別
`#[UseResource(resourceClass: '...')]`	指定關聯的 API Resource 類別
`#[UseResourceCollection(resourceCollectionClass: '...')]`	指定關聯的 Resource Collection 類別

Enum 支援（於 v13.2.0 加入）

於 v13.2.0，#[Queue] 與 #[Connection] 開始接受 enum。如此便可使用 PHP enum 取代字串字面值，型別安全地指定 Queue 與 Connection。

// Queue 名稱的 enum 定義
enum Queue: string
{
    case Default = 'default';
    case High = 'high';
    case Low = 'low';
    case Emails = 'emails';
    case Orders = 'orders';
}

// Connection 的 enum 定義
enum Connection: string
{
    case Redis = 'redis';
    case Sqs = 'sqs';
    case Database = 'database';
    case Sync = 'sync';
}

use Illuminate\Queue\Attributes\Queue;
use Illuminate\Queue\Attributes\Connection;

// 使用 enum 的型別安全指定
#[Queue(Queue::Orders)]
#[Connection(Connection::Redis)]
class ProcessOrder implements ShouldQueue
{
    // ...
}

使用 enum 可防止 Queue 名稱或 Connection 名稱的拼字錯誤，並可利用 IDE 的補完。適合在整個應用程式集中管理 Queue 名稱與 Connection 名稱。

與傳統類別屬性的比較

Attribute 的優點

宣告式 — 觀察類別開頭即可一眼看出 Job 的行為
型別安全 — 使用 enum 可享有 IDE 補完與型別檢查
與繼承的親和性 — 父類別的 attribute 可於子類別覆寫
減少程式碼 — 不需宣告屬性或覆寫方法

Attribute 的缺點

無法設定動態值 — attribute 的引數僅能為編譯時常數。無法使用變數或設定檔的值
需適應 — 團隊有時需要適應 PHP 8 的 attribute 語法

需要動態值時

若希望於執行時決定值，仍使用傳統的方法覆寫。

class ProcessOrder implements ShouldQueue
{
    // 動態的 backoff 以方法定義
    public function backoff(): array
    {
        return [
            config('queue.backoff.first'),
            config('queue.backoff.second'),
        ];
    }
}

Attributes 於 PHP 編譯時被解析。無法使用 config() 或 env() 這類執行時的值。若需要動態設定，請繼續使用類別屬性或方法。

實作機制

Laravel 內部使用 Reflection API 讀取 attribute。當 Queue Worker dispatch Job 時，ReadsQueueAttributes trait（包含於 InteractsWithQueue 中）以 reflection 偵測 attribute，並將值設定至對應屬性。

// 內部讀取的示意（已簡化）
$reflection = new ReflectionClass($job);
$attributes = $reflection->getAttributes(Queue::class);

foreach ($attributes as $attribute) {
    $instance = $attribute->newInstance();
    $job->queue = $instance->queue instanceof UnitEnum
        ? $instance->queue->value
        : $instance->queue;
}

Eloquent 模型的 attribute 也同樣，於相當於 Model::booted() 的時機以 reflection 讀取。

​什麼是 PHP Attributes

​Queue 相關 Attributes

​#[Queue] — 指定 Queue 名稱

​#[Connection] — 指定 Connection

​#[Backoff] — 指定重試 backoff 時間

​#[Tries] — 指定重試次數

​#[Timeout] — 指定 Timeout

​#[MaxExceptions] — 指定容許例外次數

​#[UniqueFor] — 指定唯一期間

​#[DeleteWhenMissingModels] — 模型不存在時刪除

​#[WithoutRelations] — 排除關聯

​#[FailOnTimeout] — Timeout 時視為失敗

​組合多個 Queue Attributes

​Eloquent 相關 Attributes

​#[ScopedBy] — 指定 Global Scope

​#[ObservedBy] — 指定 Observer

​#[UseEloquentBuilder] — 指定自訂 Query Builder

​#[CollectedBy] — 指定自訂 Collection

​#[Table] — 一次指定 Table 相關設定

​#[Scope] — 將方法定義為本地 Scope

​#[UseFactory] — 指定 Factory 類別

​其他 Eloquent Attributes

​Enum 支援（於 v13.2.0 加入）

​與傳統類別屬性的比較

​Attribute 的優點

​Attribute 的缺點

​需要動態值時

​實作機制

​下一步

中階：Queue 與 Job

PHP Reflection API

什麼是 PHP Attributes

Queue 相關 Attributes

`#[Queue]` — 指定 Queue 名稱

`#[Connection]` — 指定 Connection

`#[Backoff]` — 指定重試 backoff 時間

`#[Tries]` — 指定重試次數

`#[Timeout]` — 指定 Timeout

`#[MaxExceptions]` — 指定容許例外次數

`#[UniqueFor]` — 指定唯一期間

`#[DeleteWhenMissingModels]` — 模型不存在時刪除

`#[WithoutRelations]` — 排除關聯

`#[FailOnTimeout]` — Timeout 時視為失敗

組合多個 Queue Attributes

Eloquent 相關 Attributes

`#[ScopedBy]` — 指定 Global Scope

`#[ObservedBy]` — 指定 Observer

`#[UseEloquentBuilder]` — 指定自訂 Query Builder

`#[CollectedBy]` — 指定自訂 Collection

`#[Table]` — 一次指定 Table 相關設定

`#[Scope]` — 將方法定義為本地 Scope

`#[UseFactory]` — 指定 Factory 類別

其他 Eloquent Attributes

Enum 支援（於 v13.2.0 加入）

與傳統類別屬性的比較

Attribute 的優點

Attribute 的缺點

需要動態值時

實作機制

下一步