天堂中文在线最新版www,国产成人一区二区三区影院动漫

什么是查詢范圍？

局部查詢范圍

全局查詢范圍

#如何創(chuàng)建全局查詢范圍

#應(yīng)用全局查詢范圍

#匿名全局查詢范圍

#忽略全局查詢范圍

#全局查詢范圍注意事項

測試局部查詢范圍

在控制器中測試范圍

結(jié)論

首頁

后端開發(fā)

php教程

學會在Laravel中掌握查詢范圍

Emily Anne Brown

Mar 06, 2025 am 02:28 AM

<img src="/static/imghw/default1.png" data-src="https://img.php.cn/upload/article/000/000/000/174119929536701.jpg" class="lazy" alt="Learn to master Query Scopes in Laravel"> 在構(gòu)建Laravel應(yīng)用程序時，您可能需要編寫具有約束條件的查詢，這些約束條件在整個應(yīng)用程序中的多個地方使用。也許您正在構(gòu)建一個多租戶應(yīng)用程序，并且您必須不斷向查詢中添加<code>where</code>約束以按用戶的團隊進行篩選?；蛘?，也許您正在構(gòu)建一個博客，并且您必須不斷向查詢中添加<code>where</code>約束以篩選博客文章是否已發(fā)布。 在Laravel中，我們可以使用查詢范圍來幫助我們將這些約束條件整潔地保存在一個地方并重復使用。 在本文中，我們將研究局部查詢范圍和全局查詢范圍。我們將學習兩者之間的區(qū)別，如何創(chuàng)建您自己的查詢范圍，以及如何編寫它們的測試。 在閱讀完本文后，您應(yīng)該能夠自信地在Laravel應(yīng)用程序中使用查詢范圍。 <h1 id="什么是查詢范圍">什么是查詢范圍？</h1> <hr> 查詢范圍允許您以可重用的方式在Eloquent查詢中定義約束條件。它們通常定義為Laravel模型上的方法，或者作為實現(xiàn)<code>IlluminateDatabaseEloquentScope</code>接口的類。 它們不僅非常適合在一個地方定義可重用的邏輯，而且還可以通過將復雜的查詢約束隱藏在簡單的函數(shù)調(diào)用之后來使您的代碼更具可讀性。 查詢范圍分為兩種類型： <ul> <li>局部查詢范圍 - 您必須手動將這些范圍應(yīng)用于您的查詢。</li> <li>全局查詢范圍 - 默認情況下，這些范圍會應(yīng)用于模型上的所有查詢，前提是已注冊該查詢。</li> </ul> 如果您曾經(jīng)使用過Laravel內(nèi)置的“軟刪除”功能，您可能已經(jīng)在不知不覺中使用了查詢范圍。Laravel使用局部查詢范圍為您提供模型上的<code>withTrashed</code>和<code>onlyTrashed</code>等方法。它還使用全局查詢范圍自動向模型上的所有查詢添加<code>whereNull('deleted_at')</code>約束，以便默認情況下查詢中不會返回軟刪除的記錄。 讓我們來看看如何在Laravel應(yīng)用程序中創(chuàng)建和使用局部查詢范圍和全局查詢范圍。 <h1 id="局部查詢范圍">局部查詢范圍</h1> <hr> 局部查詢范圍定義為Eloquent模型上的方法，允許您定義可以手動應(yīng)用于模型查詢的約束條件。 假設(shè)我們正在構(gòu)建一個具有管理面板的博客應(yīng)用程序。在管理面板中，我們有兩個頁面：一個用于列出已發(fā)布的博客文章，另一個用于列出未發(fā)布的博客文章。 我們假設(shè)博客文章是使用<code>AppModelsArticle</code>模型訪問的，并且數(shù)據(jù)庫表具有一個可為空的<code>published_at</code>列，用于存儲博客文章的發(fā)布時間。如果<code>published_at</code>列在過去，則該博客文章被認為已發(fā)布。如果<code>published_at</code>列在未來或為<code>null</code>，則該博客文章被認為未發(fā)布。 要獲取已發(fā)布的博客文章，我們可以編寫如下查詢： <pre class="brush:php;toolbar:false"><code>use App\Models\Article; $publishedPosts = Article::query() ->where('published_at', '<', now()) ->get();</code></pre> 要獲取未發(fā)布的博客文章，我們可以編寫如下查詢： <pre class="brush:php;toolbar:false"><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></pre> 上面的查詢并不特別復雜。但是，假設(shè)我們在整個應(yīng)用程序中的多個地方使用它們。隨著出現(xiàn)次數(shù)的增加，我們犯錯或忘記在一個地方更新查詢的可能性越來越大。例如，開發(fā)人員可能會意外地使用<code>>=</code>而不是<code><</code>來查詢已發(fā)布的博客文章?；蛘撸_定博客文章是否已發(fā)布的邏輯可能會更改，我們需要更新所有查詢。 這就是查詢范圍非常有用的地方。因此，讓我們通過在<code>AppModelsArticle</code>模型上創(chuàng)建局部查詢范圍來整理我們的查詢。 局部查詢范圍是通過創(chuàng)建一個以<code>scope</code>開頭并以范圍的預期名稱結(jié)尾的方法來定義的。例如，名為<code>scopePublished</code>的方法將在模型上創(chuàng)建一個<code>published</code>范圍。該方法應(yīng)該接受一個<code>IlluminateContractsDatabaseEloquentBuilder</code>實例并返回一個<code>IlluminateContractsDatabaseEloquentBuilder</code>實例。 我們將這兩個范圍都添加到<code>AppModelsArticle</code>模型中： <pre class="brush:php;toolbar:false"><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', '<', now()); } public function scopeNotPublished(Builder $query): Builder { return $query->where(function (Builder $query): Builder { return $query->whereNull('published_at') ->orWhere('published_at', '>', now()); }); } // ... }</code> 正如我們在上面的示例中看到的，我們將<code>where</code>約束從之前的查詢移動到了兩個單獨的方法中：<code>scopePublished</code>和<code>scopeNotPublished</code>。我們現(xiàn)在可以在我們的查詢中像這樣使用這些范圍： <pre class="brush:php;toolbar:false"><code>use App\Models\Article; $publishedPosts = Article::query() ->published() ->get(); $unpublishedPosts = Article::query() ->notPublished() ->get();</code></pre> 在我個人看來，我發(fā)現(xiàn)這些查詢更容易閱讀和理解。這也意味著如果我們將來需要使用相同約束條件編寫任何查詢，我們可以重復使用這些范圍。 <h1 id="全局查詢范圍">全局查詢范圍</h1> <hr> 全局查詢范圍執(zhí)行與局部查詢范圍類似的功能。但是，它不是在逐個查詢的基礎(chǔ)上手動應(yīng)用，而是自動應(yīng)用于模型上的所有查詢。 正如我們前面提到的，Laravel內(nèi)置的“軟刪除”功能使用了<code>IlluminateDatabaseEloquentSoftDeletingScope</code>全局查詢范圍。此范圍會自動向模型上的所有查詢添加<code>whereNull('deleted_at')</code>約束。如果您有興趣了解其底層工作原理，可以在這里查看GitHub上的源代碼。 例如，假設(shè)您正在構(gòu)建一個具有管理面板的多租戶博客應(yīng)用程序。您可能只想允許用戶查看屬于其團隊的文章。因此，您可能會編寫如下查詢： <pre class="brush:php;toolbar:false"><code>use App\Models\Article; $publishedPosts = Article::query() ->where('published_at', '<', now()) ->get();</code></pre> 此查詢很好，但很容易忘記添加<code>where</code>約束。如果您正在編寫另一個查詢并忘記添加約束，則最終會在您的應(yīng)用程序中出現(xiàn)一個錯誤，該錯誤將允許用戶與不屬于其團隊的文章進行交互。當然，我們不希望發(fā)生這種情況！ 為了防止這種情況，我們可以創(chuàng)建一個全局范圍，我們可以將其自動應(yīng)用于我們所有<code>AppModelArticle</code>模型查詢。 <h3 id="如何創(chuàng)建全局查詢范圍">#如何創(chuàng)建全局查詢范圍</h3> 讓我們創(chuàng)建一個全局查詢范圍，該范圍按<code>team_id</code>列過濾所有查詢。 請注意，為了本文的目的，我們保持示例簡單。在實際應(yīng)用程序中，您可能希望使用更強大的方法來處理用戶未經(jīng)身份驗證或用戶屬于多個團隊等情況。但現(xiàn)在，讓我們保持簡單，以便我們可以專注于全局查詢范圍的概念。 我們將首先在終端中運行以下Artisan命令： <pre class="brush:php;toolbar:false"><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></pre> 這應(yīng)該已經(jīng)創(chuàng)建了一個新的<code>app/Models/Scopes/TeamScope.php</code>文件。我們將對此文件進行一些更新，然后查看完成的代碼： <pre class="brush:php;toolbar:false"><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', '<', now()); } public function scopeNotPublished(Builder $query): Builder { return $query->where(function (Builder $query): Builder { return $query->whereNull('published_at') ->orWhere('published_at', '>', now()); }); } // ... }</code></pre> 在上面的代碼示例中，我們可以看到我們有一個新的類，它實現(xiàn)了<code>IlluminateDatabaseEloquentScope</code>接口并具有一個名為<code>apply</code>的單個方法。這就是我們定義要應(yīng)用于模型查詢的約束條件的方法。 我們的全局范圍現(xiàn)在可以使用了。我們可以將其添加到任何我們想要將查詢范圍縮小到用戶團隊的模型中。 讓我們將其應(yīng)用于<code>AppModelsArticle</code>模型。 <h3 id="應(yīng)用全局查詢范圍">#應(yīng)用全局查詢范圍</h3> 有多種方法可以將全局范圍應(yīng)用于模型。第一種方法是在模型上使用<code>IlluminateDatabaseEloquentAttributesScopedBy</code>屬性： <pre class="brush:php;toolbar:false"><code>use App\Models\Article; $publishedPosts = Article::query() ->published() ->get(); $unpublishedPosts = Article::query() ->notPublished() ->get();</code></pre> 另一種方法是在模型的<code>booted</code>方法中使用<code>addGlobalScope</code>方法： <pre class="brush:php;toolbar:false"><code>use App\Models\Article; $articles = Article::query() ->where('team_id', Auth::user()->team_id) ->get();</code></pre> 這兩種方法都將<code>where('team_id', Auth::user()->team_id)</code>約束應(yīng)用于<code>AppModelsArticle</code>模型上的所有查詢。 這意味著您現(xiàn)在可以編寫查詢，而無需擔心按<code>team_id</code>列進行過濾： <pre class="brush:php;toolbar:false"><code>php artisan make:scope TeamScope</code></pre> 如果我們假設(shè)用戶屬于<code>team_id</code>為<code>1</code>的團隊，則將為上面的查詢生成以下SQL： <pre class="brush:php;toolbar:false"><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></pre> 這很酷，對吧？！ <h3 id="匿名全局查詢范圍">#匿名全局查詢范圍</h3> 定義和應(yīng)用全局查詢范圍的另一種方法是使用匿名全局范圍。 讓我們更新我們的<code>AppModelsArticle</code>模型以使用匿名全局范圍： <pre class="brush:php;toolbar:false"><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></pre> 在上面的代碼示例中，我們使用了<code>addGlobalScope</code>方法在模型的<code>booted</code>方法中定義匿名全局范圍。<code>addGlobalScope</code>方法接受兩個參數(shù)： <ul> <li>范圍的名稱 - 如果您需要在查詢中忽略它，則可以使用此名稱來引用范圍</li> <li>范圍約束 - 定義要應(yīng)用于查詢的約束的閉包</li> </ul> 與其他方法一樣，這會將<code>where('team_id', Auth::user()->team_id)</code>約束應(yīng)用于<code>AppModelsArticle</code>模型上的所有查詢。 根據(jù)我的經(jīng)驗，匿名全局范圍不如在單獨的類中定義全局范圍常見。但了解它們可用是很有好處的，以備不時之需。 <h3 id="忽略全局查詢范圍">#忽略全局查詢范圍</h3> 有時您可能希望編寫一個不使用已應(yīng)用于模型的全局查詢范圍的查詢。例如，您可能正在構(gòu)建一個需要包含所有記錄的報表或分析查詢，而不管全局查詢范圍如何。 如果是這種情況，您可以使用兩種方法之一來忽略全局范圍。 第一種方法是<code>withoutGlobalScopes</code>。如果未向其傳遞任何參數(shù)，此方法允許您忽略模型上的所有全局范圍： <pre class="brush:php;toolbar:false"><code>use App\Models\Article; $publishedPosts = Article::query() ->where('published_at', '<', now()) ->get();</code></pre> 或者，如果您只想忽略給定的一組全局范圍，您可以將范圍名稱傳遞給<code>withoutGlobalScopes</code>方法： <pre class="brush:php;toolbar:false"><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></pre> 在上面的示例中，我們忽略了<code>AppModelsScopesTeamScope</code>和另一個名為<code>another_scope</code>的虛構(gòu)匿名全局范圍。 或者，如果您只想忽略單個全局范圍，可以使用<code>withoutGlobalScope</code>方法： <pre class="brush:php;toolbar:false"><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', '<', now()); } public function scopeNotPublished(Builder $query): Builder { return $query->where(function (Builder $query): Builder { return $query->whereNull('published_at') ->orWhere('published_at', '>', now()); }); } // ... }</code></pre> <h3 id="全局查詢范圍注意事項">#全局查詢范圍注意事項</h3> 務(wù)必記住，全局查詢范圍僅應(yīng)用于通過模型進行的查詢。如果您使用<code>IlluminateSupportFacadesDB</code>外觀編寫數(shù)據(jù)庫查詢，則不會應(yīng)用全局查詢范圍。 例如，假設(shè)您編寫了此查詢，您希望它只抓取屬于登錄用戶的團隊的文章： <pre class="brush:php;toolbar:false"><code>use App\Models\Article; $publishedPosts = Article::query() ->published() ->get(); $unpublishedPosts = Article::query() ->notPublished() ->get();</code></pre> 在上面的查詢中，即使在<code>AppModelsArticle</code>模型上定義了<code>AppModelsScopesTeamScope</code>全局查詢范圍，也不會應(yīng)用該范圍。因此，您需要確保在數(shù)據(jù)庫查詢中手動應(yīng)用約束條件。 <h1 id="測試局部查詢范圍">測試局部查詢范圍</h1> <hr> 既然我們已經(jīng)學習了如何創(chuàng)建和使用查詢范圍，那么我們將研究如何為它們編寫測試。 有多種方法可以測試查詢范圍，您選擇的方法可能取決于您的個人喜好或您正在編寫的范圍的內(nèi)容。例如，您可能希望為范圍編寫更多單元樣式的測試?；蛘撸赡芟Ｍ帉懜嗉蓸邮降臏y試，這些測試會在諸如控制器之類的上下文中測試范圍。 就我個人而言，我喜歡混合使用兩者，這樣我就可以確信范圍正在添加正確的約束，并且范圍實際上正在查詢中使用。 讓我們從前面的示例<code>published</code>和<code>notPublished</code>范圍開始，并為它們編寫一些測試。我們將需要編寫兩個不同的測試（每個范圍一個）： <ul> <li>一個測試檢查<code>published</code>范圍只返回已發(fā)布的文章。</li> <li>一個測試檢查<code>notPublished</code>范圍只返回未發(fā)布的文章。</li> </ul> 讓我們看看這些測試，然后討論正在做的事情： <pre class="brush:php;toolbar:false"><code>use App\Models\Article; $publishedPosts = Article::query() ->where('published_at', '<', now()) ->get();</code></pre> 我們可以在上面的測試文件中看到，我們首先在<code>setUp</code>方法中創(chuàng)建一些數(shù)據(jù)。我們創(chuàng)建了兩篇已發(fā)布的文章、一篇未安排的文章和一篇已安排的文章。 然后是一個測試（<code>only_published_articles_are_returned</code>），它檢查<code>published</code>范圍只返回已發(fā)布的文章。還有一個測試（<code>only_not_published_articles_are_returned</code>），它檢查<code>notPublished</code>范圍只返回未發(fā)布的文章。 通過這樣做，我們現(xiàn)在可以確信我們的查詢范圍正在按預期應(yīng)用約束條件。 <h1 id="在控制器中測試范圍">在控制器中測試范圍</h1> <hr> 正如我們提到的，測試查詢范圍的另一種方法是在控制器中使用的上下文中測試它們。雖然范圍的隔離測試可以幫助斷言范圍正在向查詢添加正確的約束，但它實際上并沒有測試范圍是否按預期在應(yīng)用程序中使用。例如，您可能忘記向控制器方法中的查詢添加<code>published</code>范圍。 通過編寫斷言在控制器方法中使用范圍時返回正確數(shù)據(jù)的測試，可以捕獲這些類型的錯誤。 讓我們以具有多租戶博客應(yīng)用程序的示例為例，并為列出文章的控制器方法編寫一個測試。我們假設(shè)我們有一個非常簡單的控制器方法，如下所示： <pre class="brush:php;toolbar:false"><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></pre> 我們假設(shè)<code>AppModelsArticle</code>模型已應(yīng)用我們的<code>AppModelsScopesTeamScope</code>。 我們將要斷言只返回屬于用戶團隊的文章。測試用例可能如下所示： <pre class="brush:php;toolbar:false"><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', '<', now()); } public function scopeNotPublished(Builder $query): Builder { return $query->where(function (Builder $query): Builder { return $query->whereNull('published_at') ->orWhere('published_at', '>', now()); }); } // ... }</code></pre> 在上面的測試中，我們正在創(chuàng)建兩個團隊。然后，我們創(chuàng)建一個屬于團隊一的用戶。我們?yōu)閳F隊一創(chuàng)建 3 篇文章，為團隊二創(chuàng)建 2 篇文章。然后，我們充當用戶并向列出文章的控制器方法發(fā)出請求?？刂破鞣椒☉?yīng)該只返回屬于團隊一的 3 篇文章，因此我們通過比較文章的 ID 來斷言只返回這些文章。 這意味著我們可以確信全局查詢范圍正在控制器方法中按預期使用。 <h1 id="結(jié)論">結(jié)論</h1> <hr> 在本文中，我們學習了局部查詢范圍和全局查詢范圍。我們學習了它們之間的區(qū)別，如何創(chuàng)建和使用它們，以及如何為它們編寫測試。 希望您現(xiàn)在應(yīng)該能夠自信地在Laravel應(yīng)用程序中使用查詢范圍。

以上是學會在Laravel中掌握查詢范圍的詳細內(nèi)容。更多信息請關(guān)注PHP中文網(wǎng)其他相關(guān)文章！

本站聲明

本文內(nèi)容由網(wǎng)友自發(fā)貢獻，版權(quán)歸原作者所有，本站不承擔相應(yīng)法律責任。如您發(fā)現(xiàn)有涉嫌抄襲侵權(quán)的內(nèi)容，請聯(lián)系admin@php.cn