Laravel master タスクスケジュール

イントロダクションIntroduction

過去において、サーバで実行をスケジュールする必要のあるタスクごとに、Cronエントリを制作していたかと思いmす。しかし、タスクのスケジュールはソースコントロールできませんし、Cronエントリを追加するためにSSHでサーバに接続する必要があるため、これはすぐに面倒になります。In the past, you may have generated a Cron entry for each task you needed to schedule on your server. However, this can quickly become a pain, because your task schedule is no longer in source control and you must SSH into your server to add additional Cron entries.

Laravelのコマンドスケジューラは、Laravel自身の中でコマンドの実行スケジュールをスラスラと記述的に定義できるようにしてくれます。スケジューラを使用すると、サーバにはCronエントリがたった一つだけで済みます。タスクスケジュールは、app/Console/Kernel.phpファイルのscheduleメソッドで定義します。使いはじめる手助けになるように、サンプルがこのメソッドで定義済みです。Laravel's command scheduler allows you to fluently and expressively define your command schedule within Laravel itself. When using the scheduler, only a single Cron entry is needed on your server. Your task schedule is defined in the app/Console/Kernel.php file's schedule method. To help you get started, a simple example is defined within the method.

スケジューラを使いはじめるStarting The Scheduler

スケジューラを使用するには、サーバに以下のCronエントリを追加するだけです。サーバにどうやってCronエントリを追加するかわからない場合は、Cronエントリを管理できるLaravel Forgeのようなサービスを使用することを考慮してください。When using the scheduler, you only need to add the following Cron entry to your server. If you do not know how to add Cron entries to your server, consider using a service such as Laravel Forge[https://forge.laravel.com] which can manage the Cron entries for you:

* * * * * php /path/to/artisan schedule:run >> /dev/null 2>&1

このCronはLaravelコマンドスケジューラを毎分呼び出します。schedule:runコマンドが実行されると、Laravelはスケジュールされているジョブを評価し、実行する必要のあるジョブを起動します。This Cron will call the Laravel command scheduler every minute. When the schedule:run command is executed, Laravel will evaluate your scheduled tasks and runs the tasks that are due.

スケジュール定義Defining Schedules

スケジュールタスクは全部App\Console\Kernelクラスのscheduleメソッドの中に定義します。手始めに、スケジュールタスクの例を見てください。この例は毎日深夜１２時に「クロージャ」をスケジュールしています。「クロージャ」の中でテーブルをクリアするデータベースクエリを実行しています。You may define all of your scheduled tasks in the schedule method of the App\Console\Kernel class. To get started, let's look at an example of scheduling a task. In this example, we will schedule a Closure to be called every day at midnight. Within the Closure we will execute a database query to clear a table:

<?php

namespace App\Console;

use DB;
use Illuminate\Console\Scheduling\Schedule;
use Illuminate\Foundation\Console\Kernel as ConsoleKernel;

class Kernel extends ConsoleKernel
{
    /**
     * アプリケーションで提供するArtisanコマンド
     *
     * @var array
     */
    protected $commands = [
        \App\Console\Commands\Inspire::class,
    ];

    /**
     * アプリケーションのコマンド実行スケジュール定義
     *
     * @param  \Illuminate\Console\Scheduling\Schedule  $schedule
     * @return void
     */
    protected function schedule(Schedule $schedule)
    {
        $schedule->call(function () {
            DB::table('recent_users')->delete();
        })->daily();
    }
}

「クロージャ」の呼び出しをスケジュールするほかにArtisanコマンドとオペレーティングシステムコマンドを実行できます。例として、Artisanコマンドをコマンド名かクラスを使いスケジュールするcommandメソッドを使ってみましょう。In addition to scheduling Closure calls, you may also schedule Artisan commands[/docs/{{version}}/artisan] and operating system commands. For example, you may use the command method to schedule an Artisan command using either the command's name or class:

$schedule->command('emails:send --force')->daily();

$schedule->command(EmailsCommand::class, ['--force'])->daily();

オペレーティングシステムでコマンドを実行するためにはexecメソッドを使います。The exec command may be used to issue a command to the operating system:

$schedule->exec('node /home/forge/script.js')->daily();

繰り返しのスケジュールオプションSchedule Frequency Options

もちろん、タスクは様々なスケジュールを割り付けることができます。Of course, there are a variety of schedules you may assign to your task:

これらのメソッドは週の特定の曜日だけに実行させるために、追加の制約と組み合わせ細かく調整できます。These methods may be combined with additional constraints to create even more finely tuned schedules that only run on certain days of the week. For example, to schedule a command to run weekly on Monday:

// 週に一回、月曜の13:00に実行
$schedule->call(function () {
    //
})->weekly()->mondays()->at('13:00');

// ウィークエンドの8時から17時まで一時間ごとに実行
$schedule->command('foo')
          ->weekdays()
          ->hourly()
          ->timezone('America/Chicago')
          ->between('8:00', '17:00');

以下が追加のスケジュール制約のリストです。Below is a list of the additional schedule constraints:

時間制限Between Time Constraints

betweenメソッドは一日の時間に基づき、実行時間を制限するために使用します。The between method may be used to limit the execution of a task based on the time of day:

$schedule->command('reminders:send')
                    ->hourly()
                    ->between('7:00', '22:00');

同じように、unlessBetweenメソッドは、その時間にタスクの実行を除外するために使用します。Similarly, the unlessBetween method can be used to exclude the execution of a task for a period of time:

$schedule->command('reminders:send')
                    ->hourly()
                    ->unlessBetween('23:00', '4:00');

真値テスト制約Truth Test Constraints

whenメソッドは指定した真値テストの結果に基づき制限を実行します。言い換えれば指定した「クロージャ」がtureを返し、他の制約が実行を停止しない限りタスクを実行します。The when method may be used to limit the execution of a task based on the result of a given truth test. In other words, if the given Closure returns true, the task will execute as long as no other constraining conditions prevent the task from running:

$schedule->command('emails:send')->daily()->when(function () {
    return true;
});

skipメソッドはwhenをひっくり返したものです。skipメソッドへ渡したクロージャがtrueを返した時、スケジュールタスクは実行されます。The skip method may be seen as the inverse of when. If the skip method returns true, the scheduled task will not be executed:

$schedule->command('emails:send')->daily()->skip(function () {
    return true;
});

whenメソッドをいくつかチェーンした場合は、全部のwhen条件がtrueを返すときのみスケジュールされたコマンドが実行されます。When using chained when methods, the scheduled command will only execute if all when conditions return true.

タスク多重起動の防止Preventing Task Overlaps

デフォルトでは以前の同じジョブが起動中であっても、スケジュールされたジョブは実行されます。これを防ぐには、withoutOverlappingメソッドを使用してください。By default, scheduled tasks will be run even if the previous instance of the task is still running. To prevent this, you may use the withoutOverlapping method:

$schedule->command('emails:send')->withoutOverlapping();

この例の場合、emails:send Artisanコマンドは実行中でない限り毎分実行されます。withoutOverlappingメソッドは指定したタスクの実行時間の変動が非常に大きく、予想がつかない場合に特に便利です。In this example, the emails:send Artisan command[/docs/{{version}}/artisan] will be run every minute if it is not already running. The withoutOverlapping method is especially useful if you have tasks that vary drastically in their execution time, preventing you from predicting exactly how long a given task will take.

タスク出力Task Output

Laravelスケジューラはスケジュールしたタスクが生成する出力を取り扱う便利なメソッドをたくさん用意しています。最初にsendOutputToメソッドを使い、後ほど内容を調べられるようにファイルへ出力してみましょう。The Laravel scheduler provides several convenient methods for working with the output generated by scheduled tasks. First, using the sendOutputTo method, you may send the output to a file for later inspection:

$schedule->command('emails:send')
         ->daily()
         ->sendOutputTo($filePath);

出力を指定したファイルに追加したい場合は、appendOutputToメソッドを使います。If you would like to append the output to a given file, you may use the appendOutputTo method:

$schedule->command('emails:send')
         ->daily()
         ->appendOutputTo($filePath);

emailOutputToメソッドを使えば、選択したメールアドレスへ出力をメールで送ることができます。最初にsendOutputToメソッドを使い、ファイルへ出力しておく必要があることに注意してください。また、タスクの出力をメールで送る前に、Laravelのメールサービスの設定を済ませておく必要もあります。Using the emailOutputTo method, you may e-mail the output to an e-mail address of your choice. Note that the output must first be sent to a file using the sendOutputTo method. Before e-mailing the output of a task, you should configure Laravel's e-mail services[/docs/{{version}}/mail]:

$schedule->command('foo')
         ->daily()
         ->sendOutputTo($filePath)
         ->emailOutputTo('foo@example.com');

Note: note emailOutputTo、sendOutputTo、appendOutputToメソッドはcommandメソッド専用で、callメソッドはサポートしていません。{note} The emailOutputTo, sendOutputTo and appendOutputTo methods are exclusive to the command method and are not supported for call.

タスクフックTask Hooks

beforeとafterメソッドを使えば、スケジュールされたタスクの実行前後に指定したコードを実行することができます。Using the before and after methods, you may specify code to be executed before and after the scheduled task is complete:

$schedule->command('emails:send')
         ->daily()
         ->before(function () {
             // タスク開始時…
         })
         ->after(function () {
             // タスク終了時…
         });

URLへのPingPinging URLs

pingBeforeとthenPingメソッドを使用し、タスク実行前、タスク完了後に指定したURLへ自動的にPingすることができます。これはLaravel Envoyerのような外部サービスへスケジュールされたタスクが始まる、または完了したことを知らせるのに便利です。Using the pingBefore and thenPing methods, the scheduler can automatically ping a given URL before or after a task is complete. This method is useful for notifying an external service, such as Laravel Envoyer[https://envoyer.io], that your scheduled task is commencing or has finished execution:

$schedule->command('emails:send')
         ->daily()
         ->pingBefore($url)
         ->thenPing($url);

pingBefore($url)かthenPing($url)のどちらを使用するにも、Guzzle HTTPライブラリーが必要です。GuzzleはComposerパッケージマネージャを利用し追加できます。Using either the pingBefore($url) or thenPing($url) feature requires the Guzzle HTTP library. You can add Guzzle to your project using the Composer package manager:

composer require guzzlehttp/guzzle