php artisan schedule:run とは？
Laravel のタスクスケジューラを動かすためのエントリーポイントです。
cron に 1 分ごとに実行させる だけで、Kernel.php で定義したすべてのスケジュール済みジョブが実行されます。
スケジュール定義場所
// app/Console/Kernel.php
protected function schedule(Schedule $schedule)
{
// 例: 毎日 02:00 にコマンドを実行
$schedule->command('emails:send')->dailyAt('02:00');
// 例: 毎時ジョブをディスパッチ
$schedule->job(new SyncUsers())->hourly();
// 例: 10 分ごとにクロージャを呼び出し
$schedule->call(fn () => Log::info('Heartbeat'))
->everyTenMinutes();
}
ポイント：すべてのスケジュールは
Kernel.phpに集約します。
実行方法
| コマンド | 用途 | 推奨環境 |
|---|---|---|
php artisan schedule:run | スケジューラを 1 回だけ走らせる（cron から呼び出す） | 本番（1 分ごとの cron） |
php artisan schedule:work | スケジューラを長時間走らせる（開発・Docker など） | 開発・コンテナ |
php artisan schedule:clear | スケジュールキャッシュをクリア | 変更後に必須 |
本番 では cron で毎分呼び出すだけです。
開発時はschedule:workが便利です。
主要オプション
| オプション | 説明 | 必須 | 例 |
|---|---|---|---|
--only=task-name | 特定タスクのみ実行 | いいえ | --only=emails:send |
--queue=queue-name | ジョブを指定キューでディスパッチ | いいえ | --queue=high |
--stop-when=condition | 条件が満たされたら停止 | いいえ | --stop-when=not-in-production |
--help | ヘルプ表示 | いいえ | --help |
--verbose | 詳細ログ | いいえ | --verbose |
--stop-whenはstopWhen()で渡したクロージャで判定します。
シンプルな実行例
// routes/console.php
Artisan::command('emails:send', function () {
$this->info('Sending emails…');
})->describe('Send queued emails');
protected function schedule(Schedule $schedule)
{
$schedule->command('emails:send')
->dailyAt('02:00')
->withoutOverlapping()
->onOneServer();
}
cron 行 (Linux)
* * * * * cd /path/to/project && php artisan schedule:run >> /dev/null 2>&1
よくある落とし穴
| 問題 | 対策 |
|---|---|
| スケジューラが動かない | cron が正しいパスと PHP バイナリを指しているか確認 |
| 同時実行でジョブが重複 | ->onOneServer() か ->sharedLock() を使用 |
| ログが残らない | ->sendOutputTo(storage_path('logs/scheduler.log')) を追加 |
| タイムゾーンずれ | .env の APP_TIMEZONE と cron のタイムゾーンを合わせる |
ベストプラクティス
| 実践 | 理由 |
|---|---|
| スケジュールをバージョン管理 | コードと同じリポジトリに置く |
| スケジューラ内で重い処理をしない | 重い作業はジョブへ委譲 |
withoutOverlapping() を使う | 同期重複を防止 |
変更後は schedule:clear | キャッシュをリセット |
| ログを出力 | 実行履歴を追える |
開発時は schedule:work | cron 設定不要 |
すぐに使えるコードスニペット
// Kernel.php
protected function schedule(Schedule $schedule)
{
$schedule->command('emails:send')
->dailyAt('02:00')
->withoutOverlapping()
->sendOutputTo(storage_path('logs/email-scheduler.log'));
$schedule->job(new SyncUsers())->hourly();
$schedule->call(fn () => Log::info('Heartbeat'))
->everyTenMinutes();
}
# 本番
* * * * * php artisan schedule:run >> /dev/null 2>&1
# 開発
php artisan schedule:work
まとめ
php artisan schedule:run は「1 分ごとに呼び出すだけで、すべてのスケジュール済みタスクが自動で処理される」シンプルさが魅力です。Kernel.php でスケジュールを宣言し、cron を 1 行だけ設定するだけで、バージョン管理済みかつ監査可能な背景ジョブシステムが完成します。
