學會在Laravel中掌握查詢範圍

在構建Laravel應用程序時，您可能需要編寫具有約束條件的查詢，這些約束條件在整個應用程序中的多個地方使用。也許您正在構建一個多租戶應用程序，並且您必須不斷向查詢中添加where約束以按用戶的團隊進行篩選。或者，也許您正在構建一個博客，並且您必須不斷向查詢中添加where約束以篩選博客文章是否已發布。

在Laravel中，我們可以使用查詢範圍來幫助我們將這些約束條件整潔地保存在一個地方並重複使用。

在本文中，我們將研究局部查詢範圍和全局查詢範圍。我們將學習兩者之間的區別，如何創建您自己的查詢範圍，以及如何編寫它們的測試。

在閱讀完本文後，您應該能夠自信地在Laravel應用程序中使用查詢範圍。

什麼是查詢範圍？

---

查詢範圍允許您以可重用的方式在Eloquent查詢中定義約束條件。它們通常定義為Laravel模型上的方法，或者作為實現IlluminateDatabaseEloquentScope接口的類。

它們不僅非常適合在一個地方定義可重用的邏輯，而且還可以通過將復雜的查詢約束隱藏在簡單的函數調用之後來使您的代碼更具可讀性。

查詢範圍分為兩種類型：

• 局部查詢範圍 - 您必須手動將這些範圍應用於您的查詢。
• 全局查詢範圍 - 默認情況下，這些範圍會應用於模型上的所有查詢，前提是已註冊該查詢。

如果您曾經使用過Laravel內置的“軟刪除”功能，您可能已經在不知不覺中使用了查詢範圍。 Laravel使用局部查詢範圍為您提供模型上的withTrashed和onlyTrashed等方法。它還使用全局查詢範圍自動向模型上的所有查詢添加whereNull('deleted_at')約束，以便默認情況下查詢中不會返回軟刪除的記錄。

讓我們來看看如何在Laravel應用程序中創建和使用局部查詢範圍和全局查詢範圍。

局部查詢範圍

---

局部查詢範圍定義為Eloquent模型上的方法，允許您定義可以手動應用於模型查詢的約束條件。

假設我們正在構建一個具有管理面板的博客應用程序。在管理面板中，我們有兩個頁面：一個用於列出已發布的博客文章，另一個用於列出未發布的博客文章。

我們假設博客文章是使用AppModelsArticle模型訪問的，並且數據庫表具有一個可為空的published_at列，用於存儲博客文章的發佈時間。如果published_at列在過去，則該博客文章被認為已發布。如果published_at列在未來或為null，則該博客文章被認為未發布。

要獲取已發布的博客文章，我們可以編寫如下查詢：

<code>use App\Models\Article;

$publishedPosts = Article::query()
    ->where('published_at', 'get();</code>

要獲取未發布的博客文章，我們可以編寫如下查詢：

<code>use App\Models\Article;
use Illuminate\Contracts\Database\Eloquent\Builder;

$unpublishedPosts = Article::query()
    ->where(function (Builder $query): void {
        $query->whereNull('published_at')
            ->orWhere('published_at', '>', now());
    })
    ->get();</code>

上面的查詢並不特別複雜。但是，假設我們在整個應用程序中的多個地方使用它們。隨著出現次數的增加，我們犯錯或忘記在一個地方更新查詢的可能性越來越大。例如，開發人員可能會意外地使用>=而不是來查詢已發布的博客文章。或者，確定博客文章是否已發布的邏輯可能會更改，我們需要更新所有查詢。

這就是查詢範圍非常有用的地方。因此，讓我們通過在AppModelsArticle模型上創建局部查詢範圍來整理我們的查詢。

局部查詢範圍是通過創建一個以scope開頭並以範圍的預期名稱結尾的方法來定義的。例如，名為scopePublished的方法將在模型上創建一個published範圍。該方法應該接受一個IlluminateContractsDatabaseEloquentBuilder實例並返回一個IlluminateContractsDatabaseEloquentBuilder實例。

我們將這兩個範圍都添加到AppModelsArticle模型中：

<code>declare(strict_types=1);

namespace App\Models;

use Illuminate\Contracts\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

final class Article extends Model
{
    public function scopePublished(Builder $query): Builder
    {
        return $query->where('published_at', 'where(function (Builder $query): Builder {
            return $query->whereNull('published_at')
                ->orWhere('published_at', '>', now());
        });
    }

    // ...
}</code>

正如我們在上面的示例中看到的，我們將where約束從之前的查詢移動到了兩個單獨的方法中：scopePublished和scopeNotPublished。我們現在可以在我們的查詢中像這樣使用這些範圍：

<code>use App\Models\Article;

$publishedPosts = Article::query()
    ->published()
    ->get();

$unpublishedPosts = Article::query()
    ->notPublished()
    ->get();</code>

在我個人看來，我發現這些查詢更容易閱讀和理解。這也意味著如果我們將來需要使用相同約束條件編寫任何查詢，我們可以重複使用這些範圍。

全局查詢範圍

---

全局查詢範圍執行與局部查詢範圍類似的功能。但是，它不是在逐個查詢的基礎上手動應用，而是自動應用於模型上的所有查詢。

正如我們前面提到的，Laravel內置的“軟刪除”功能使用了IlluminateDatabaseEloquentSoftDeletingScope全局查詢範圍。此範圍會自動向模型上的所有查詢添加whereNull('deleted_at')約束。如果您有興趣了解其底層工作原理，可以在這裡查看GitHub上的源代碼。

例如，假設您正在構建一個具有管理面板的多租戶博客應用程序。您可能只想允許用戶查看屬於其團隊的文章。因此，您可能會編寫如下查詢：

<code>use App\Models\Article;

$publishedPosts = Article::query()
    ->where('published_at', 'get();</code>

此查詢很好，但很容易忘記添加where約束。如果您正在編寫另一個查詢並忘記添加約束，則最終會在您的應用程序中出現一個錯誤，該錯誤將允許用戶與不屬於其團隊的文章進行交互。當然，我們不希望發生這種情況！

為了防止這種情況，我們可以創建一個全局範圍，我們可以將其自動應用於我們所有AppModelArticle模型查詢。

#如何創建全局查詢範圍

讓我們創建一個全局查詢範圍，該範圍按team_id列過濾所有查詢。

請注意，為了本文的目的，我們保持示例簡單。在實際應用程序中，您可能希望使用更強大的方法來處理用戶未經身份驗證或用戶屬於多個團隊等情況。但現在，讓我們保持簡單，以便我們可以專注於全局查詢範圍的概念。

我們將首先在終端中運行以下Artisan命令：

<code>use App\Models\Article;
use Illuminate\Contracts\Database\Eloquent\Builder;

$unpublishedPosts = Article::query()
    ->where(function (Builder $query): void {
        $query->whereNull('published_at')
            ->orWhere('published_at', '>', now());
    })
    ->get();</code>

這應該已經創建了一個新的app/Models/Scopes/TeamScope.php文件。我們將對此文件進行一些更新，然後查看完成的代碼：

<code>declare(strict_types=1);

namespace App\Models;

use Illuminate\Contracts\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

final class Article extends Model
{
    public function scopePublished(Builder $query): Builder
    {
        return $query->where('published_at', 'where(function (Builder $query): Builder {
            return $query->whereNull('published_at')
                ->orWhere('published_at', '>', now());
        });
    }

    // ...
}</code>

在上面的代碼示例中，我們可以看到我們有一個新的類，它實現了IlluminateDatabaseEloquentScope接口並具有一個名為apply的單個方法。這就是我們定義要應用於模型查詢的約束條件的方法。

我們的全局範圍現在可以使用了。我們可以將其添加到任何我們想要將查詢範圍縮小到用戶團隊的模型中。

讓我們將其應用於AppModelsArticle模型。

#應用全局查詢範圍

有多種方法可以將全局範圍應用於模型。第一種方法是在模型上使用IlluminateDatabaseEloquentAttributesScopedBy屬性：

<code>use App\Models\Article;

$publishedPosts = Article::query()
    ->published()
    ->get();

$unpublishedPosts = Article::query()
    ->notPublished()
    ->get();</code>

另一種方法是在模型的booted方法中使用addGlobalScope方法：

<code>use App\Models\Article;

$articles = Article::query()
    ->where('team_id', Auth::user()->team_id)
    ->get();</code>

這兩種方法都將where('team_id', Auth::user()->team_id)約束應用於AppModelsArticle模型上的所有查詢。

這意味著您現在可以編寫查詢，而無需擔心按team_id列進行過濾：

<code>php artisan make:scope TeamScope</code>

如果我們假設用戶屬於team_id為1的團隊，則將為上面的查詢生成以下SQL：

<code>declare(strict_types=1);

namespace App\Models\Scopes;

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Scope;
use Illuminate\Support\Facades\Auth;

final readonly class TeamScope implements Scope
{
    /**
     * Apply the scope to a given Eloquent query builder.
     */
    public function apply(Builder $builder, Model $model): void
    {
        $builder->where('team_id', Auth::user()->team_id);
    }
}</code>

這很酷，對吧？ ！

#匿名全局查詢範圍

定義和應用全局查詢範圍的另一種方法是使用匿名全局範圍。

讓我們更新我們的AppModelsArticle模型以使用匿名全局範圍：

<code>declare(strict_types=1);

namespace App\Models;

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

#[ScopedBy(TeamScope::class)]
final class Article extends Model
{
    // ...
}</code>

在上面的代碼示例中，我們使用了addGlobalScope方法在模型的booted方法中定義匿名全局範圍。 addGlobalScope方法接受兩個參數：

• 範圍的名稱 - 如果您需要在查詢中忽略它，則可以使用此名稱來引用範圍
• 範圍約束 - 定義要應用於查詢的約束的閉包

與其他方法一樣，這會將where('team_id', Auth::user()->team_id)約束應用於AppModelsArticle模型上的所有查詢。

根據我的經驗，匿名全局範圍不如在單獨的類中定義全局範圍常見。但了解它們可用是很有好處的，以備不時之需。

#忽略全局查詢範圍

有時您可能希望編寫一個不使用已應用於模型的全局查詢範圍的查詢。例如，您可能正在構建一個需要包含所有記錄的報表或分析查詢，而不管全局查詢範圍如何。

如果是這種情況，您可以使用兩種方法之一來忽略全局範圍。

第一種方法是withoutGlobalScopes。如果未向其傳遞任何參數，此方法允許您忽略模型上的所有全局範圍：

<code>use App\Models\Article;

$publishedPosts = Article::query()
    ->where('published_at', 'get();</code>

或者，如果您只想忽略給定的一組全局範圍，您可以將範圍名稱傳遞給withoutGlobalScopes方法：

<code>use App\Models\Article;
use Illuminate\Contracts\Database\Eloquent\Builder;

$unpublishedPosts = Article::query()
    ->where(function (Builder $query): void {
        $query->whereNull('published_at')
            ->orWhere('published_at', '>', now());
    })
    ->get();</code>

在上面的示例中，我們忽略了AppModelsScopesTeamScope和另一個名為another_scope的虛構匿名全局範圍。

或者，如果您只想忽略單個全局範圍，可以使用withoutGlobalScope方法：

<code>declare(strict_types=1);

namespace App\Models;

use Illuminate\Contracts\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

final class Article extends Model
{
    public function scopePublished(Builder $query): Builder
    {
        return $query->where('published_at', 'where(function (Builder $query): Builder {
            return $query->whereNull('published_at')
                ->orWhere('published_at', '>', now());
        });
    }

    // ...
}</code>

#全局查詢範圍注意事項

務必記住，全局查詢範圍僅應用於通過模型進行的查詢。如果您使用IlluminateSupportFacadesDB外觀編寫數據庫查詢，則不會應用全局查詢範圍。

例如，假設您編寫了此查詢，您希望它只抓取屬於登錄用戶的團隊的文章：

<code>use App\Models\Article;

$publishedPosts = Article::query()
    ->published()
    ->get();

$unpublishedPosts = Article::query()
    ->notPublished()
    ->get();</code>

在上面的查詢中，即使在AppModelsArticle模型上定義了AppModelsScopesTeamScope全局查詢範圍，也不會應用該範圍。因此，您需要確保在數據庫查詢中手動應用約束條件。

測試局部查詢範圍

---

既然我們已經學習瞭如何創建和使用查詢範圍，那麼我們將研究如何為它們編寫測試。

有多種方法可以測試查詢範圍，您選擇的方法可能取決於您的個人喜好或您正在編寫的範圍的內容。例如，您可能希望為範圍編寫更多單元樣式的測試。或者，您可能希望編寫更多集成樣式的測試，這些測試會在諸如控制器之類的上下文中測試範圍。

就我個人而言，我喜歡混合使用兩者，這樣我就可以確信範圍正在添加正確的約束，並且範圍實際上正在查詢中使用。

讓我們從前面的示例published和notPublished範圍開始，並為它們編寫一些測試。我們將需要編寫兩個不同的測試（每個範圍一個）：

• 一個測試檢查published範圍只返回已發布的文章。
• 一個測試檢查notPublished範圍只返回未發布的文章。

讓我們看看這些測試，然後討論正在做的事情：

<code>use App\Models\Article;

$publishedPosts = Article::query()
    ->where('published_at', 'get();</code>

我們可以在上面的測試文件中看到，我們首先在setUp方法中創建一些數據。我們創建了兩篇已發布的文章、一篇未安排的文章和一篇已安排的文章。

然後是一個測試（only_published_articles_are_returned），它檢查published範圍只返回已發布的文章。還有一個測試（only_not_published_articles_are_returned），它檢查notPublished範圍只返回未發布的文章。

通過這樣做，我們現在可以確信我們的查詢範圍正在按預期應用約束條件。

在控制器中測試範圍

---

正如我們提到的，測試查詢範圍的另一種方法是在控制器中使用的上下文中測試它們。雖然範圍的隔離測試可以幫助斷言範圍正在向查詢添加正確的約束，但它實際上並沒有測試範圍是否按預期在應用程序中使用。例如，您可能忘記向控制器方法中的查詢添加published範圍。

通過編寫斷言在控制器方法中使用範圍時返回正確數據的測試，可以捕獲這些類型的錯誤。

讓我們以具有多租戶博客應用程序的示例為例，並為列出文章的控制器方法編寫一個測試。我們假設我們有一個非常簡單的控制器方法，如下所示：

<code>use App\Models\Article;
use Illuminate\Contracts\Database\Eloquent\Builder;

$unpublishedPosts = Article::query()
    ->where(function (Builder $query): void {
        $query->whereNull('published_at')
            ->orWhere('published_at', '>', now());
    })
    ->get();</code>

我們假設AppModelsArticle模型已應用我們的AppModelsScopesTeamScope。

我們將要斷言只返回屬於用戶團隊的文章。測試用例可能如下所示：

<code>declare(strict_types=1);

namespace App\Models;

use Illuminate\Contracts\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

final class Article extends Model
{
    public function scopePublished(Builder $query): Builder
    {
        return $query->where('published_at', 'where(function (Builder $query): Builder {
            return $query->whereNull('published_at')
                ->orWhere('published_at', '>', now());
        });
    }

    // ...
}</code>

在上面的測試中，我們正在創建兩個團隊。然後，我們創建一個屬於團隊一的用戶。我們為團隊一創建 3 篇文章，為團隊二創建 2 篇文章。然後，我們充當用戶並向列出文章的控制器方法發出請求。控制器方法應該只返回屬於團隊一的 3 篇文章，因此我們通過比較文章的 ID 來斷言只返回這些文章。

這意味著我們可以確信全局查詢範圍正在控制器方法中按預期使用。

結論

---

在本文中，我們學習了局部查詢範圍和全局查詢範圍。我們學習了它們之間的區別，如何創建和使用它們，以及如何為它們編寫測試。

希望您現在應該能夠自信地在Laravel應用程序中使用查詢範圍。

以上是學會在Laravel中掌握查詢範圍的詳細內容。更多資訊請關注PHP中文網其他相關文章！