★ 简介

在过去，开发者必须为每个需要调度的任务生成单独的 Cron 项目。然而令人头疼的是任务调度不受版本控制，并且需要 SSH 到服务器上来增加 Cron 条目。

Laravel 命令调度器允许你在 Laravel 中对命令调度进行清晰流畅的定义，并且仅需要在服务器上增加一条 Cron 项目即可。你的调度已经定义在 app/Console/Kernel.php 文件的 schedule 方法中。为了方便你开始，在该方法内包含了一个简单的例子。你可以随意增加调度到 Schedule 对象中。

▶ 启动调度器

使用调度器时，你只需要把 Cron 添加到你的服务器，如果你不知道如何添加到服务器，你可以使用 Laravel Forge 服务来管理你的 Cron 。

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

该 Cron 将于每分钟调用一次 Laravel 命令调度器，当 schedule:run 命令执行时， Laravel 会评估你的计划任务并运行预定任务。

★ 定义调度

你可以将所有的计划任务定义在 App\Console\Kernel 类的 schedule 方法中。在开始之前，先让我们来看看一个任务的调度示例。在该例子中，我们计划了一个会在每天午夜被调用的 Closure 。该 Closure 将运行数据库查询语句来清除某个数据表：

<?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();
    }
}

除了计划 Closure 调用，你还能计划 Artisan 命令 以及系统命令操作。举个例子，你可以使用 command 方法传参命令名称或者命令类名称来计划一个 Artisan 命令：

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

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

exec 命令可发送命令到操作系统上：

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

▶ 调度频率设置

当然，你可以针对你的任务来分配多种调度计划：

这些方法可以合并其它限制条件以生成更精确的调度。例如在某周的某几天运行调度。举个例子，计划一个每周周一的调度：

// 每周一的下午一点钟运行
$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 方法可以用来判断是否要运行任务，主要基于一个指定的为真验证的运行结果。如果指定的 Closure 返回 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 时才运行。

▶ 避免任务重复

默认情况，即便之前相同的任务主体仍未结束，现有计划任务依旧会被运行。为了避免这个问题，你可以使用 withoutOverlapping 方法：

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

在这个例子中，如果没有其它 emails:sendArtisan 命令 在运行的话，此任务将于每分钟被运行一次。当你有些任务运行时间过长，且无法预测出具体所需时间时，withoutOverlapping 方法将会特别有帮助。

▶ 维护模式

当应用进入 维护模式 时，默认情况下 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 方法，你可以发送输出到你所指定的电子邮件上。注意，你必须先通过 sendOutputTo 方法将其输出到一个文件。同时，在邮件发出之前，你需要先设置 Laravel 的 电子邮件服务:

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

{note} emailOutputTo， sendOutputTo 和 appendOutputTo 方法只适用于 command 方法，不支持 call 方法。

★ 任务钩子

通过 before 与 after 方法，你能让特定的代码在任务完成之前及之后运行：

$schedule->command('emails:send')
         ->daily()
         ->before(function () {
             // 任务就要开始了…
         })
         ->after(function () {
             // 任务完成…
         });

■ Ping 网址

通过 pingBefore 与 thenPing 方法，调度器能自动的在一个任务完成之前或之后 ping 一个指定的网址。该方法在你计划的任务进行或完成时，可用来有效的通知一个外部服务，例如 Laravel Envoyer：

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

不论使用 pingBefore($url) 或 thenPing($url) 功能都需要 Guzzle HTTP 函数库的支持。你可以使用 Composer 将 Guzzle 函数库添加到你的项目中：

composer require guzzlehttp/guzzle