任务调度

• 简介
• 定义调度
  • 调度 Artisan 命令
  • 调度队列任务
  • 调度 Shell 命令
  • 调度频率选项
  • 时区
  • 避免任务重复
  • 在一台服务器上运行任务
  • 后台任务
  • 维护模式
• 任务输出
• 任务钩子

简介

过去，您可能需要在服务器上为每个调度的任务都生成 Cron 计划任务。但是，这很快就变得很痛苦，因为任务调度不再受源代码控制，并且必须通过 SSH 连接到服务器才能添加其它 Cron 计划任务。

Laravel 的调度程序允许您在 Laravel 自身内流畅而清晰地定义命令调度。使用调度程序时，服务器上只需要一个 Cron 计划任务。任务调度在 app/Console/Kernel.php 文件的 schedule 方法中定义。为帮助您入门，此方法中定义了一个简单示例。

启动调度程序

使用调度程序时，只需将以下 Cron 计划任务添加到服务器即可。如果您不知道如何将 Cron 计划任务添加到服务器，可以考虑使用管理 Cron 计划任务的服务，比如 Laravel Forge：

* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

此 Cron 计划任务会每分钟调用 Laravel 的命令调度程序。执行 schedule:run 命令后，Laravel 会检查调度的任务并运行到期的任务。

定义调度

可以在 App\Console\Kernel 类的 schedule 方法中定义所有调度的任务。首先，我们看一个调度任务的示例。在此示例中，我们计划在每天的零点调用一个闭包函数。在闭包中，执行一条数据库语句清空数据表：

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 = [
        //
    ];

    /**
     * 定义应用的命令调度
     *
     * @param  \Illuminate\Console\Scheduling\Schedule  $schedule
     * @return void
     */
    protected function schedule(Schedule $schedule)
    {
        $schedule->call(function () {
            DB::table('recent_users')->delete();
        })->daily();
    }
}

除了使用闭包调度之外，还可以使用 invokable 对象。Invokable 对象是一个包含 __invoke 方法的简单的 PHP 类：

$schedule->call(new DeleteRecentUsers)->daily();

调度 Artisan 命令

除了调度闭包调用之外，还可以调度 Artisan 命令 和操作系统命令。例如，可以在 command 方法中用命令名称或类调度 Artisan 命令：

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

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

调度队列任务

job 方法可用于调度 队列任务。此方法提供了一种方便的方法调度任务，而无需使用 call 方法手动创建闭包将任务添加到队列：

$schedule->job(new Heartbeat)->everyFiveMinutes();

// 分发任务到「heartbeats」队列
$schedule->job(new Heartbeat, 'heartbeats')->everyFiveMinutes();

调度 Shell 命令

exec 方法可用于向操作系统发送命令：

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

调度频率选项

当然，有各种调度可以指定给任务：

这些方法可以结合其它条件，创建仅在一周的某些天运行的更细致的调度。例如，要调度一个每周一运行的命令：

// 每周一的下午 1 点运行一次
$schedule->call(function () {
    //
})->weekly()->mondays()->at('13:00');

// 从每周的上午 8 点到下午 5 点，每小时运行一次
$schedule->command('foo')
          ->weekdays()
          ->hourly()
          ->timezone('America/Chicago')
          ->between('8:00', '17:00');

以下是其它调度限制的列表：

时间范围限制

between 方法可用于限制任务在一天的一段时间内执行：

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

同样，unlessBetween 方法可用于限制任务在除一段时间以外的其它时间执行：

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

闭包可信测试限制

when 方法可用于限制任务基于给定的可信测试结果运行。换句话说，如果给定闭包返回 true，只要没有其它限制条件阻止任务运行，任务就会执行：

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

skip 方法可以看作是与 when 相反的方法。如果 skip 方法返回 true，调度的任务不会被执行：

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

当链式调用 when 方法时，调度的命令只会在所有 when 条件返回 true 时才执行。

环境限制

environments 方法可用于仅在给定环境下执行任务：

$schedule->command('emails:send')
            ->daily()
            ->environments(['staging', 'production']);

时区

使用 timezone 方法，可以指定调度的任务的时间应该按给定时区解释：

$schedule->command('report:generate')
         ->timezone('America/New_York')
         ->at('02:00')

请注意，一些时区使用夏令时。当夏令时生效时，调度的任务可能会执行两次或者根本不执行。因此，我们建议尽可能避免时区调度。

避免任务重复

默认情况下，即使以前的任务实例仍在运行，调度的任务会运行。要防止这种情况，可以使用 withoutOverlapping 方法：

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

在此示例中，如果 Artisan 命令 emails:send 尚未运行，它会每分钟运行一次。当任务的执行的时间起伏很大，无法准确预测给定任务将花费多长时间时，withoutOverlapping 方法尤其有用。

如有需要，可以指定在「不重复」锁定过期前必须经过多少分钟。默认情况下，锁定会在 24 小时后过期：

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

在一台服务器上运行任务

要使用此功能，应用必须使用 memcached 或 redis 作为应用默认的缓存驱动。此外，所有服务器必须和同一中央缓存服务器通信。

如果应用运行在多台服务器上，可以限制调度的任务只在一台服务器上运行。例如，假设有一个在每周五晚上生成新报告的调度任务。如果任务调度程序运行在三台服务器上，那么任务调度程序会在三台服务器上都运行并生成三次报告。不好吧！

要指示任务只应该在一台服务器上运行，可以在定义调度任务时使用 onOneServer 方法。第一台服务器取得任务时会获得任务的原子锁避免其它服务器在同一时间运行同一任务：

$schedule->command('report:generate')
                ->fridays()
                ->at('17:00')
                ->onOneServer();

后台任务

默认情况下，同时调度的多个命令会按顺序执行。如果有长时间运行的命令，可能导致后续命令启动比预期时间要晚。如果要在后台运行命令以便它们可以同时运行，可以使用 runInBackground 方法：

$schedule->command('analytics:report')
         ->daily()
         ->runInBackground();

维护模式

当 Laravel 处于 维护模式 时不会运行调度的任务，因为我们我们不希望任务干扰服务器执行任何未完成的维护。但是，如果要在维护模式时强制运行任务，可以使用 evenInMaintenanceMode 方法：

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

任务输出

Laravel 的调度程序提供了几个方便的方法来处理调度的任务生成的输出。首先，使用 sendOutputTo 方法，可以将输出发送到文件以供以后查阅：

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

如果要追加输出到给定文件，可以使用 appendOutputTo 方法：

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

使用 emailOutputTo 方法，可以向所选的邮件地址发送邮件。在通过邮件发送任务的输出之前，应该配置 Laravel 的 邮件服务：

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

emailOutputTo，sendOutputTo 和 appendOutputTo 方法专门用于 command 和 exec 方法。

任务钩子

使用 before 和 after 方法，可以指定在调度的任务完成之前或之后要执行的代码：

$schedule->command('emails:send')
         ->daily()
         ->before(function () {
             // 任务即将开始
         })
         ->after(function () {
             // 任务已完成
         });

Ping URL

使用 pingBefore 和 thenPing 方法，调度程序会在任务完成之前或之后自动 ping 给定的 URL。此方法对于通知外部服务（如 Laravel Envoyer）调度的任务正在开始执行或已执行完成时很有用：

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

pingBeforeIf 和 thenPingIf 方法可用于仅当给定条件为 true 时 ping 给定的 URL：

$schedule->command('emails:send')
         ->daily()
         ->pingBeforeIf($condition, $url)
         ->thenPingIf($condition, $url);

所有 ping 方法都需要 Guzzle HTTP 库。可以使用 Composer 包管理器将 Guzzle 添加到项目中：

composer require guzzlehttp/guzzle