Eloquent 的 Scope

什麼是 Scope

Eloquent 的 Scope 是能將查詢的約束彙整並重複使用的機制。Scope 分為兩種。

種類	套用時機	用途
Global Scope	恆自動套用	軟刪除、多租戶、公開篩選
本地 Scope	僅在明確呼叫時套用	「熱門文章」、「活躍使用者」等共同篩選

本地 Scope

定義

本地 Scope 透過在模型的方法上加註 #[Scope] attribute 來定義。

<?php

namespace App\Models;

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

class Post extends Model
{
    /**
     * 限定為已公開的文章
     */
    #[Scope]
    protected function published(Builder $query): void
    {
        $query->where('status', 'published');
    }

    /**
     * 限定為熱門文章
     */
    #[Scope]
    protected function popular(Builder $query): void
    {
        $query->where('views', '>', 1000);
    }
}

#[Scope] attribute 位於 Illuminate\Database\Eloquent\Attributes 命名空間，是 PHP 8.0 以後的原生語法。

使用方式

已定義的 Scope 可作為方法呼叫。也能鏈式使用。

use App\Models\Post;

// 僅取得已公開的文章
$posts = Post::published()->get();

// 取得已公開且熱門的文章，以最新順序
$posts = Post::published()->popular()->latest()->get();

傳遞參數

可於 Scope 方法的第 2 個引數以後定義額外參數。

#[Scope]
protected function ofStatus(Builder $query, string $status): void
{
    $query->where('status', $status);
}

呼叫時直接傳入引數即可。

$posts = Post::ofStatus('draft')->get();
$posts = Post::ofStatus('published')->get();

與 `orWhere` 的組合

以 orWhere 串接 Scope 時，有時需要邏輯群組。

// 使用 closure 的方式（確實但冗長）
$users = User::popular()->orWhere(function (Builder $query) {
    $query->active();
})->get();

// 使用高階方法可寫得更簡潔
$users = User::popular()->orWhere->active()->get();

Global Scope

機制

Global Scope 是實作 Illuminate\Database\Eloquent\Scope 介面的類別。此介面僅要求一個 apply 方法。

// 框架本體的介面定義
// src/Illuminate/Database/Eloquent/Scope.php

interface Scope
{
    public function apply(Builder $builder, Model $model);
}

於 apply 方法中對查詢建構器加入約束。

建立 Global Scope 類別

以 make:scope 指令產生範本。

php artisan make:scope ActiveScope

會產生 app/Models/Scopes/ActiveScope.php。

<?php

namespace App\Models\Scopes;

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

class ActiveScope implements Scope
{
    /**
     * 將 Scope 套用至查詢建構器
     */
    public function apply(Builder $builder, Model $model): void
    {
        $builder->where('is_active', true);
    }
}

套用至模型

以 #[ScopedBy] attribute 註冊（推薦）

Laravel 13 中使用 #[ScopedBy] attribute 最為簡潔。

<?php

namespace App\Models;

use App\Models\Scopes\ActiveScope;
use Illuminate\Database\Eloquent\Attributes\ScopedBy;
use Illuminate\Database\Eloquent\Model;

#[ScopedBy([ActiveScope::class])]
class User extends Model
{
    //
}

可以陣列指定多個 Scope。

#[ScopedBy([ActiveScope::class, TenantScope::class])]
class User extends Model
{
    //
}

於 booted() 方法手動註冊

也可以覆寫 booted 方法並呼叫 addGlobalScope。

<?php

namespace App\Models;

use App\Models\Scopes\ActiveScope;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    protected static function booted(): void
    {
        static::addGlobalScope(new ActiveScope);
    }
}

加入 Global Scope 後，User::all() 等所有查詢都會自動附加 WHERE is_active = 1。

以匿名 Closure 定義 Global Scope

單純且不至於為其建立獨立檔案的 Scope，可以 closure 定義。

protected static function booted(): void
{
    static::addGlobalScope('active', function (Builder $builder) {
        $builder->where('is_active', true);
    });
}

要排除以 closure 定義的 Scope，需使用 Scope 名稱（字串）而非類別名稱。

Global Scope 的排除

有時希望於特定查詢停用 Scope。

use App\Models\Scopes\ActiveScope;

// 排除特定 Scope
User::withoutGlobalScope(ActiveScope::class)->get();

// 排除以 closure 定義的 Scope
User::withoutGlobalScope('active')->get();

// 排除所有 Global Scope
User::withoutGlobalScopes()->get();

// 排除多個 Scope
User::withoutGlobalScopes([ActiveScope::class, TenantScope::class])->get();

// 除指定 Scope 以外全數排除
User::withoutGlobalScopesExcept([TenantScope::class])->get();

框架內部：SoftDeletingScope

觀察 Laravel 標準的 SoftDeletes trait 如何運用 Global Scope，即可掌握實作模式。 SoftDeletingScope 實作了 Scope 介面。

// src/Illuminate/Database/Eloquent/SoftDeletingScope.php

class SoftDeletingScope implements Scope
{
    protected $extensions = [
        'Restore', 'RestoreOrCreate', 'CreateOrRestore',
        'WithTrashed', 'WithoutTrashed', 'OnlyTrashed',
    ];

    /**
     * 將 Scope 套用至查詢建構器
     * 加入僅取得 deleted_at 為 NULL 之記錄的限制
     */
    public function apply(Builder $builder, Model $model)
    {
        $builder->whereNull($model->getQualifiedDeletedAtColumn());
    }

    /**
     * 為查詢建構器擴充 macro
     * 讓 withTrashed() / onlyTrashed() 等可以使用
     */
    public function extend(Builder $builder)
    {
        foreach ($this->extensions as $extension) {
            $this->{"add{$extension}"}($builder);
        }

        // 覆寫 delete() 操作為更新 deleted_at 的處理
        $builder->onDelete(function (Builder $builder) {
            $column = $this->getDeletedAtColumn($builder);
            return $builder->update([
                $column => $builder->getModel()->freshTimestampString(),
            ]);
        });
    }
}

來看 withTrashed() 的實作

withTrashed() 實際上是呼叫 withoutGlobalScope($this)。也就是排除 SoftDeletingScope 自身，讓已刪除記錄也可取得。

protected function addWithTrashed(Builder $builder)
{
    $builder->macro('withTrashed', function (Builder $builder, $withTrashed = true) {
        if (! $withTrashed) {
            return $builder->withoutTrashed();
        }

        return $builder->withoutGlobalScope($this);
    });
}

onlyTrashed() 同樣是排除自身後再加上 whereNotNull('deleted_at')。

protected function addOnlyTrashed(Builder $builder)
{
    $builder->macro('onlyTrashed', function (Builder $builder) {
        $model = $builder->getModel();

        $builder->withoutGlobalScope($this)->whereNotNull(
            $model->getQualifiedDeletedAtColumn()
        );

        return $builder;
    });
}

Scope 介面並未定義 extend 方法，但 Eloquent 的 Builder 若發現 Scope 具備 extend 方法就會自動呼叫。可用於新增自訂 macro。

實務使用情境

多租戶：以租戶 ID 自動篩選

SaaS 應用程式中，對所有查詢自動套用租戶 ID 篩選相當重要。

<?php

namespace App\Models\Scopes;

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

class TenantScope implements Scope
{
    public function apply(Builder $builder, Model $model): void
    {
        if ($tenantId = auth()->user()?->tenant_id) {
            $builder->where('tenant_id', $tenantId);
        }
    }
}

use App\Models\Scopes\TenantScope;
use Illuminate\Database\Eloquent\Attributes\ScopedBy;

#[ScopedBy([TenantScope::class])]
class Post extends Model
{
    //
}

如此只要呼叫 Post::all() 就會只回傳驗證中使用者的租戶資料。

公開/非公開篩選

於管理後台希望顯示未公開的文章，但於前端僅顯示已公開者的情境。

<?php

namespace App\Models\Scopes;

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

class PublishedScope implements Scope
{
    public function apply(Builder $builder, Model $model): void
    {
        $builder->where('status', 'published')
                ->where('published_at', '<=', now());
    }
}

於管理後台以 withoutGlobalScope 排除 Scope。

// 前端：僅顯示已公開（自動套用 PublishedScope）
$posts = Post::latest()->get();

// 管理後台：顯示所有文章
$posts = Post::withoutGlobalScope(PublishedScope::class)->latest()->get();

使用 `addSelect` 而非 `select`

於 Global Scope 中加入欄位時，請使用 addSelect 而非 select。使用 select 會覆寫呼叫端查詢中 select 的欄位。

// 錯誤範例：覆寫呼叫端的 select
public function apply(Builder $builder, Model $model): void
{
    $builder->select('id', 'tenant_id', 'name');
}

// 正確範例：在既有 select 上追加
public function apply(Builder $builder, Model $model): void
{
    $builder->addSelect('tenant_id');
}

下一步

Eloquent 自訂 Cast

學習將屬性轉換邏輯實作為自訂 Cast，並活用 Value Object 模式的方法。

AI 開發

設計模式

套件開發

應用程式結構

Laravel 13 新功能

Eloquent 深入探索

驗證擴充

認證擴充

安全性

佇列

測試

什麼是 Scope

本地 Scope

定義

使用方式

傳遞參數

與 `orWhere` 的組合

Global Scope

機制

建立 Global Scope 類別

套用至模型

以匿名 Closure 定義 Global Scope

Global Scope 的排除

框架內部：SoftDeletingScope

實務使用情境

多租戶：以租戶 ID 自動篩選

公開/非公開篩選

使用 `addSelect` 而非 `select`

下一步

Eloquent 自訂 Cast

​什麼是 Scope

​本地 Scope

​定義

​使用方式

​傳遞參數

​與 orWhere 的組合

​Global Scope

​機制

​建立 Global Scope 類別

​套用至模型

​以匿名 Closure 定義 Global Scope

​Global Scope 的排除

​框架內部：SoftDeletingScope

​實務使用情境

​多租戶：以租戶 ID 自動篩選

​公開/非公開篩選

​使用 addSelect 而非 select

​下一步

Eloquent 自訂 Cast

什麼是 Scope

本地 Scope

定義

使用方式

傳遞參數

與 `orWhere` 的組合

Global Scope

機制

建立 Global Scope 類別

套用至模型

以匿名 Closure 定義 Global Scope

Global Scope 的排除

框架內部：SoftDeletingScope

實務使用情境

多租戶：以租戶 ID 自動篩選

公開/非公開篩選

使用 `addSelect` 而非 `select`

下一步