Zenn
❓

Laravel のスコープメソッドってなに？

2025/02/27に公開
Laravel
PHP
tech

🔍 Laravel のスコープメソッドをわかりやすく解説！

スコープメソッド（Scope Methods） とは、Eloquent モデルのクエリを簡潔に記述できる 再利用可能なクエリロジック のことです。

これを使うことで、データベースからの取得条件を 統一して管理 でき、コードの可読性と保守性が向上します！✨

✨ スコープメソッドの基本

Laravel では、スコープメソッドには 「ローカルスコープ」 と 「グローバルスコープ」 の 2 種類がありますが、まずは 「ローカルスコープ」 について解説します！

✅ ローカルスコープとは？

特定の条件を 再利用可能なメソッドとして定義 し、Eloquent クエリに適用できるようにするものです。

💡 ポイント

  • scope というプレフィックスを付けてメソッドを定義（例：scopeActive()）
  • メソッドの最初の引数は必ず Builder インスタンスを受け取る
  • クエリのチェーンメソッドとして呼び出し可能

🛠️ スコープメソッドの使い方

1️⃣ スコープメソッドを定義

まずは User モデルに アクティブユーザー（status が active のユーザー）を取得するスコープ を作成します。

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

class User extends Model
{
    // 🔽 スコープメソッドの定義
    public function scopeActive(Builder $query)
    {
        return $query->where('status', 'active');
    }
}

💡 スコープ名は scope を省略して active として使えます！

2️⃣ スコープメソッドを使ってクエリを実行

定義したスコープを使って、アクティブユーザーを取得してみましょう！

$activeUsers = User::active()->get();

🔹 User::where('status', 'active')->get(); と同じ意味ですが、コードがシンプルで読みやすくなります！

3️⃣ パラメータを受け取るスコープ

例えば、特定の役職（role）を持つユーザーを取得するスコープを作る場合：

class User extends Model
{
    public function scopeRole(Builder $query, $role)
    {
        return $query->where('role', $role);
    }
}

使用例

$adminUsers = User::role('admin')->get();

🔹 User::where('role', 'admin')->get(); と同じですが、スコープ化することでコードの再利用性が向上！

🌍 グローバルスコープ

ローカルスコープは、特定のメソッドを呼び出したときに適用される のに対し、グローバルスコープはすべてのクエリに適用されるスコープ です。

例えば、常にアクティブなユーザーのみを取得するようにしたい 場合、グローバルスコープを使います。

1️⃣ グローバルスコープの定義 

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

class ActiveUserScope implements Scope
{
    public function apply(Builder $builder, Model $model)
    {
        $builder->where('status', 'active');
    }
}

2️⃣ モデルに適用 

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

3️⃣ 動作 

$users = User::all(); // 常に `status = active` のユーザーだけ取得！

💡 グローバルスコープを一時的に無効化したい場合

$users = User::withoutGlobalScope(ActiveUserScope::class)->get();

🎯 スコープメソッドを使うメリット

✅ メリット 🚀 詳細
🔹 コードの再利用性向上 何度も使うクエリを 1 か所にまとめられる！
🔹 可読性が向上 User::active() のようにシンプルに書ける！
🔹 バグを防ぎやすい 同じ条件を毎回書く必要がなく、統一できる！

🏁 まとめ

📌 項目 🔍 内容
🛠 ローカルスコープ scope プレフィックスをつけたメソッドを定義
✅ クエリの簡潔化 User::active()->get(); のようにシンプルに
🔄 パラメータ付きスコープ User::role('admin')->get(); で柔軟なクエリ
🌍 グローバルスコープ すべてのクエリにデフォルト条件を適用

Laravel のスコープメソッドを活用すれば、クエリを簡潔にしつつ、統一感のあるコードを実現できます！🎉

ぜひ活用してみてください！🚀

Discussion