Laravel 模型全局作用域与本地作用域：统一过滤关联课程可见性-php教程-PHP中文网

Laravel 模型全局作用域与本地作用域：统一过滤关联课程可见性

本文介绍如何在 Laravel 5.8 中通过本地作用域（Local Scope）和全局作用域（Global Scope）统一处理多个组件模型对 course 模型的可见性过滤（如 show = 1），避免在每个查询中重复编写 whereHas('course', ...) 逻辑。

本文介绍如何在 laravel 5.8 中通过本地作用域（local scope）和全局作用域（global scope）统一处理多个组件模型对 `course` 模型的可见性过滤（如 `show = 1`），避免在每个查询中重复编写 `wherehas('course', ...)` 逻辑。

在实际开发中，当多个模型（如 Material、Quiz、Assignment、Resource 等共 8+ 个组件）均通过 belongsTo 关联到同一个 Course 模型，且业务要求：仅展示 course.show = 1 的记录（即隐藏已下架课程对应的所有子组件），手动在每个控制器或查询构造器中重复书写 whereHas('course', fn($q) => $q->where('show', 1)) 不仅冗余，更易出错、难以维护。

此时，推荐采用分层策略：优先使用本地作用域（Local Scope） 实现显式、可复用的过滤；必要时升级为全局作用域（Global Scope） 实现自动、强制的默认行为。

✅ 方案一：定义本地作用域（推荐用于灵活控制）

在共享该关联逻辑的各个模型（如 Material.php、Quiz.php）中，统一添加一个可复用的本地作用域：

// app/Models/Material.php
public function scopeWithVisibleCourse(Builder $builder)
{
    return $builder->whereHas('course', function ($q) {
        $q->where('show', 1);
    });
}

调用时简洁清晰，语义明确：

$materials = Material::withVisibleCourse()
    ->with(['lesson', 'course.attachment'])
    ->whereIn('lesson_id', $lessons)
    ->get();

? 提示：若需支持权限判断（如仅管理员可见隐藏课程），可将 $request->user() 或 Auth::user() 注入作用域参数，例如：
scopeWithVisibleCourse(Builder $builder, User $user = null)，并在内部动态判断 $user?->can('course/show-hidden-courses')。

Laravel Cloud
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。

下载

✅ 方案二：启用全局作用域（适用于强约束场景）

当「始终过滤隐藏课程」是全站默认规则（如非管理员永远不应看到 show = 0 的课程及其关联数据），则应使用全局作用域，实现一次注册、处处生效。

创建作用域类（路径建议：app/Scopes/CourseVisibilityScope.php）：
```
<?php 
```

namespace App\Scopes;

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

class CourseVisibilityScope implements Scope { public function apply(Builder $builder, Model $model) { // 仅对存在 'course' 关系的模型生效（防御性检查） if (method_exists($model, 'course')) { $builder->whereHas('course', function ($q) { $q->where('show', 1); }); } } }

2. 在需受控的模型中注册全局作用域（如 `Material.php`）：
```php
use App\Scopes\CourseVisibilityScope;

protected static function boot()
{
    parent::boot();
    static::addGlobalScope(new CourseVisibilityScope);
}

此后所有 Eloquent 查询（包括 ::all()、::find()、with() 等）将自动注入该过滤条件：

// ✅ 自动包含 whereHas('course', ['show' => 1])
$materials = Material::with(['lesson', 'course'])->get();

// ❌ 若某处需临时绕过（如后台管理页），使用：
$materials = Material::withoutGlobalScope(CourseVisibilityScope::class)
    ->with(['lesson', 'course'])->get();

⚠️ 注意事项与最佳实践

性能考量：whereHas 会触发额外 JOIN 或子查询，若数据量大，建议为 courses.show 字段添加数据库索引。
关系健壮性：确保各组件模型的 course() 关系方法定义正确（如 return $this->belongsTo(Course::class);），否则全局作用域可能报错。
权限解耦：全局作用域不宜直接耦合用户权限逻辑（如 $request 不可用）。权限判断应前置至控制器或 Policy 层，再决定是否调用 withoutGlobalScope()。
Laravel 5.8 兼容性：上述语法完全兼容 Laravel 5.8，无需升级依赖。