Laravel : make:scope コマンド
make:scope は Eloquent スコープクラス を自動生成する Artisan コマンドです。
スコープはモデルのクエリロジックを切り出すために使われ、クラス化することで再利用性が高まります。
- カテゴリ：artisan
- バージョン：Laravel 12（PHP 8.4）
- コマンド：
php artisan make:scope {name} - 関連：
make:model、make:controller、make:migration、make:factory - 変更履歴：Laravel 10 で追加
TL;DR
| 何に使うか | Eloquent スコープクラスを素早く作成 |
| 最低限の使い方 | php artisan make:scope ActiveScope --model=User |
| よくある罠 | --model を付け忘れると use 文が生成されないスコープ名に Scope を付け忘れると名前空間が不一致になる |
1. 構文と引数
php artisan make:scope {name}
| 引数 | 型 | 必須 | 既定値 | 説明 |
|---|---|---|---|---|
name |
string | ○ | スコープクラス名（例: ActiveScope） |
|
--model |
string | × | スコープを適用したいモデル名（例: User） |
|
--force |
bool | × | false | 既存ファイルを上書きする |
戻り値
- 生成したファイルパス（文字列）
- コンソールに生成結果を表示
例外
FileNotFoundException（app/Scopes/ディレクトリがない場合）FilesystemException（書き込み失敗）
2. 生成されるコード
php artisan make:scope ActiveScope --model=User
app/Scopes/ActiveScope.php
<?php
namespace App\Scopes;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Scope;
class ActiveScope implements Scope
{
public function apply(Builder $builder, Model $model): void
{
$builder->where('is_active', true);
}
}
ポイント
use文は自動で挿入され、Scopeインターフェースを実装。- スコープクラスは
app/Scopes/に配置される。
3. 実務での使い方
3-1. グローバルスコープとして登録
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
use App\Scopes\ActiveScope;
class User extends Model
{
protected static function booted(): void
{
static::addGlobalScope(new ActiveScope);
}
}
これにより
User::all()で自動的にWHERE is_active = 1が付加される。
3-2. ローカルスコープとして利用
// コントローラでの利用例
$activeUsers = User::active()->get(); // `scopeActive()` が自動で呼び出される
スコープメソッド名は
scopeXxxと定義され、呼び出し時はxxx()になる。
4. よくある落とし穴
| 罠 | 原因 | 対処 |
|---|---|---|
--model を忘れる |
スコープクラスに use 文が生成されない |
--model=User を必ず付ける |
スコープ名に Scope を付け忘れる |
名前空間が合わない | ActiveScope のように末尾を Scope にする |
| ディレクトリがない | app/Scopes/ が存在しない |
コマンドは自動で作成するが、権限が無い場合は手動で作成 |
| キャッシュが残る | config/app.php などのキャッシュ |
php artisan config:clear、php artisan cache:clear を実行 |
5. 代替手段との比較
| 手段 | メリット | デメリット | いつ選ぶか |
|---|---|---|---|
make:scope |
コード量削減・ベストプラクティス | コマンドに依存 | プロジェクト標準化したい |
| 手動で作成 | 柔軟性高い | ミスの可能性 | 既存構造に合わせたい |
| モデル内でスコープ定義 | 直感的 | 再利用性低い | 小規模プロジェクト |
6. テスト例（Pest）
it('creates a scope class file', function () {
Artisan::call('make:scope', ['name' => 'ActiveScope', '--model' => 'User']);
expect(storage_path('app/Scopes/ActiveScope.php'))->toBeFile();
$content = file_get_contents(storage_path('app/Scopes/ActiveScope.php'));
expect($content)->toContain('class ActiveScope implements Scope');
});
