Laravel 作为一款流行的 PHP 框架，以其丰富的功能著称，能够显著提升 Web 开发效率。Laravel Scopes 便是其中一项实用功能，可用于为 Eloquent 模型定义可重用且可链接的查询约束。本文将深入解析 Laravel Scopes 的概念，并带领您逐步实现它们在 Laravel 项目中的应用。
什么是 Laravel 范围？
Laravel 作用域是一种将查询约束封装为可重用且易于使用的方法的机制。它提供了一种便捷的方式来应用查询条件，有效减少代码重复，并提升代码组织的清晰度。
Laravel 范围的类型：
Laravel 作用域的两种类型：全局作用域和局部作用域。
全球范围：
全局作用域定义在模型内部，并自动应用于该模型的所有查询。它提供了一种便捷的方式来添加始终应用的通用查询条件。例如，您可以设置一个全局作用域，默认仅检索激活用户或仅检索已发布文章。当您需要全局强制执行某些条件，而不想在每个查询中显式添加它们时，全局作用域非常有用。
生成范围
创建新的全局范围，可以使用php artisan make:scope命令，此命令能生成范围并将其放置在应用程序的app/Models/Scopes目录中：
php artisan make:scope ActiveUserScope
创建全局作用域是一个便捷的过程
1、使用 make:scope 命令生成一个实现 Illuminate\Database\Eloquent\Scope 接口的类。
2、在生成的类中实现 apply 方法。
3、在 apply 方法中，根据需要添加 where 约束或其他类型的子句，以构建所需的查询条件。
<?php
namespace App\Models\Scopes;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Scope;
class ActiveUserScope implements Scope
{
/**
* Apply the scope to a given Eloquent query builder.
*/
public function apply(Builder $builder, Model $model): void
{
$builder->where( column: 'is_active', operator: true);
}
}
应用全局范围
将全局作用域应用于模型的步骤如下：
1、重写模型的 booted 方法。
2、在 booted 方法中，调用模型的 addGlobalScope 方法。
3、将作用域的实例作为 addGlobalScope 方法的唯一参数。
<?php
namespace App\Models;
use App\Models\Scopes\ActiveUserScope;
class User extends Model
{
protected static function booted()
{
static::addGlobalScope(new ActiveUserScope());
}
}
把上例中的范围添加到 App\Models\User 模型后，再调用 all()、get()、first() 等方法，将会执行以下 SQL 查询：
select * from `users` where `is_active` = true
匿名全球范围
Eloquent 提供了使用闭包定义全局作用域的灵活性，方便创建不需要专用类的简单作用域。
1、指定自定义作用域名称作为 addGlobalScope 方法的第一个参数。
2、在闭包中，定义作用域的逻辑，通常是添加 where 约束或其他类型的子句。
/**
* The "booted" method of the model.
* @return void
*/
no usages
protected static function booted(): void
{
static::addGlobalScope( scope: 'activeUser', function (Builder $builder) {
$builder->where( column: 'is_active', operator: true);
});
}
删除全局范围
从特定查询中删除全局作用域，请使用 withoutGlobalScope 方法，此方法将全局范围的类名作为其唯一参数：
User :: withoutGlobalScope ( ActiveUserScope :: class )-> get ();
如果使用闭包定义全局作用域，请提供分配给全局作用域的字符串名称：
User :: withoutGlobalScope ( 'activeUser' )-> get ();
要删除查询的一个或多个全局范围，可以使用withoutGlobalScopes方法：
// 删除所有作用域...
User :: withoutGlobalScopes ()-> get ();
// 删除特定范围...
User :: withoutGlobalScopes ([
ActiveUserScope :: class ,
HasEmailVerifiedScope :: class
])-> get ();
本地范围：
本地范围被定义为模型内的方法，用于在每次使用的基础上应用查询约束。当您想要根据用户输入或其他因素动态应用特定条件时，本地范围非常有用。提供了一种灵活的方式来向查询添加条件，而不会污染控制器/服务/存储库代码。
作用域应始终返回相同的查询构建器实例或void：
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
/**
* @param Builder $builder
* @return void
*/
public function scopeEmailVerified(Builder $builder): void
{
$builder->whereNotNull('email_verified_at');
}
/**
* @param Builder $builder
* @return void
*/
public function scopeActiveUser(Builder $builder): void
{
$builder->where('is_active', true);
}
}
使用本地范围
定义范围后，可以在查询模型时调用其方法。但务必注意，调用该方法时不应包含范围前缀，还可以将调用链接到不同的范围：
use App\Models\User;
$users = User::emailVerified()->activeUser()->get();
在 SQL 中：
select * from `users` where `email_verified_at` is not null and `is_active` = true
要使用“or”查询运算符组合多个 Eloquent 模型范围，可能需要使用闭包来实现正确的逻辑分组：
User :: emailVerified ()-> orWhere (function (Builder $query ) {
$query -> activeUser ();
})-> get ();
在 SQL 中：
select * from `users` where (`email_verified_at` is not null or (`is_active` = true));
由于这可能会变得很麻烦，Laravel 提供了一个“更高阶”的orWhere方法，能够流畅地将范围链接在一起，而不需要闭包：
User :: emailVerified ()->orWhere-> activeUser ();
动态范围
有时可能想要定义一个接受参数的范围，只需在作用域方法的签名中包含其他参数即可，范围参数应在 $query 参数之后声明：
/**
* @param Builder $query
* @param string $role
* @return void
*/
public function scopeOfRole ( Builder $query , string $role ): void
{
$query -> where ( 'role' , $role );
}
将所需的参数添加到作用域方法的签名后，可以在调用作用域时传递这些参数：
$users = User :: ofRole ( 'admin' )-> get ();
实现 Laravel 范围：
当我们需要定义很多范围时，为了避免类文件过大，我们可以使用 Trait 来将所有范围定义在一个独立的文件中，然后让模型类使用它。
use App\Models\User\UserScopeHelper;
class User extends Model
{
use UserScopeHelper;
/** 你的代码 */
}
<?php
declare(strict_types=1);
namespace App\Models\Traits;
use Illuminate\Database\Eloquent\Builder;
trait UserScopeHelper
{
/**
* 只查询激活用户
*
* @param Builder $builder
* @return void
*/
public function scopeActiveUser(Builder $builder): void
{
$builder->where('is_active', true);
}
/**
* 只查询已验证邮箱的用户
*
* @param Builder $builder
* @return void
*/
public function scopeEmailVerified(Builder $builder): void
{
$builder->whereNotNull('email_verified_at');
}
/**
* 根据角色查询用户
*
* @param Builder $builder
* @param string $role
* @return void
*/
public function scopeOfRole(Builder $builder, string $role): void
{
$builder->where('role', $role);
}
}
为了方便使用范围，请在模型中使用 Trait：
<?php
namespace App\Models;
use App\Models\Traits\UserScopeHelper;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
use UserScopeHelper;
}
Laravel 范围的优点：
1、代码可重用性：范围允许您定义一次查询约束并在应用程序的不同部分中重用它们。这有助于消除代码重复并促进更干净、更易于维护的代码。
2、提高可读性：通过将查询约束封装在命名方法中，作用域使代码更具表现力且更易于理解。范围还有助于减少重复查询条件的噪音，从而产生更清晰、更易读的查询。
3、灵活性：Laravel 作用域提供了向查询动态添加条件的灵活性。通过本地作用域，您可以根据不同的条件轻松链接多个作用域方法，使您的代码更能适应不断变化的需求。
结论：
Laravel Scopes 提供了一种强大而优雅的方式来为 Eloquent 模型定义可重用的查询约束。通过将查询条件封装在作用域内，开发人员可以实现更简洁的代码，增强代码的可重用性，并提高 Laravel 应用程序的可维护性。凭借其易于实现和灵活性，Laravel 作用域成为所有 Laravel 开发人员的宝贵工具。
感谢分享 有用
发表评论