任务调度 · laravel 5.4

<article><h1>Laravel 的任务调度（计划任务）功能 Task Scheduling</h1><ul><li><a href="#introduction">简介</a></li><li><a href="#defining-schedules">定义调度</a><ul><li><a href="#schedule-frequency-options">调度频率设置</a></li><li><a href="#preventing-task-overlaps">避免任务重复</a></li><li><a href="#maintenance-mode">维护模式</a></li></ul></li><li><a href="#task-output">任务输出</a></li><li><a href="#task-hooks">任务钩子</a></li></ul><a name="introduction"></a><h2><a href="#introduction">简介</a></h2>在过去，开发者必须为每个需要调度的任务生成单独的 Cron 项目。然而令人头疼的是任务调度不受版本控制，并且需要 SSH 到服务器上来增加 Cron 条目。Laravel 命令调度器允许你在 Laravel 中对命令调度进行清晰流畅的定义，并且仅需要在服务器上增加一条 Cron 项目即可。你的调度已经定义在 <code class=" language-php">app/Console/Kernel.php</code> 文件的 <code class=" language-php">schedule</code> 方法中。为了方便你开始，在该方法内包含了一个简单的例子。你可以随意增加调度到 <code class=" language-php">Schedule</code> 对象中。<h3>启动调度器</h3>使用调度器时，你只需要把 Cron 添加到你的服务器，如果你不知道如何添加到服务器，你可以使用 <a href="https://forge.laravel.com">Laravel Forge</a> 服务来管理你的 Cron 。<pre class=" language-php"><code class=" language-php">* * * * * php /path/to/artisan schedule:run >> /dev/null 2>&1</code></pre>该 Cron 将于每分钟调用一次 Laravel 命令调度器，当 <code class=" language-php">schedule:run</code> 命令执行时， Laravel 会评估你的计划任务并运行预定任务。<a name="defining-schedules"></a><h2><a href="#defining-schedules">定义调度</a></h2>你可以将所有的计划任务定义在 <code class=" language-php">App\Console\Kernel</code> 类的 <code class=" language-php">schedule</code> 方法中。在开始之前，先让我们来看看一个任务的调度示例。在该例子中，我们计划了一个会在每天午夜被调用的 <code class=" language-php">闭包</code>。该 <code class=" language-php">闭包</code> 将运行数据库查询语句来清除某个数据表：<pre class=" language-php"><code class=" language-php"><?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(); } }</code></pre>除了计划 <code class=" language-php">闭包</code> 调用，你还能计划 <a href="/docs/5.4/artisan">Artisan 命令</a>以及系统命令操作。举个例子，你可以使用 <code class=" language-php">command</code> 方法传参命令名称或者命令类名称来计划一个 <code class=" language-php">Artisan</code> 命令：<pre class=" language-php"><code class=" language-php">$schedule->command('emails:send --force')->daily(); $schedule->command(EmailsCommand::class, ['--force'])->daily();</code></pre><code class=" language-php">exec</code> 命令可发送命令到操作系统上：<pre class=" language-php"><code class=" language-php">$schedule->exec('node /home/forge/script.js')->daily();</code></pre><a name="schedule-frequency-options"></a><h3>调度频率设置</h3>当然，你可以针对你的任务来分配多种调度计划：<table><thead><tr><th>方法</th><th>描述</th></tr></thead><tbody><tr><td><code class=" language-php">->cron('* * * * * *');</code></td><td>自定义调度任务</td></tr><tr><td><code class=" language-php">->everyMinute();</code></td><td> 每分钟执行一次任务</td></tr><tr><td><code class=" language-php">->everyFiveMinutes();</code></td><td>每五分钟执行一次任务</td></tr><tr><td><code class=" language-php">->everyTenMinutes();</code></td><td>每十分钟执行一次任务</td></tr><tr><td><code class=" language-php">->everyThirtyMinutes();</code></td><td>每半小时执行一次任务</td></tr><tr><td><code class=" language-php">->hourly();</code></td><td>每小时执行一次任务</td></tr><tr><td><code class=" language-php">->hourlyAt(17);</code></td><td>每一个小时的第 17 分钟运行一次</td></tr><tr><td><code class=" language-php">->daily();</code></td><td>每到午夜执行一次任务</td></tr><tr><td><code class=" language-php">->dailyAt('13:00');</code></td><td>每天的 13:00 执行一次任务</td></tr><tr><td><code class=" language-php">->twiceDaily(1, 13);</code></td><td>每天的 1:00 和 13:00 分别执行一次任务</td></tr><tr><td><code class=" language-php">->weekly();</code></td><td>每周执行一次任务</td></tr><tr><td><code class=" language-php">->monthly();</code></td><td>每月执行一次任务</td></tr><tr><td><code class=" language-php">->monthlyOn(4, '15:00');</code></td><td>在每个月的第四天的 15:00 执行一次任务</td></tr><tr><td><code class=" language-php">->quarterly();</code></td><td>每季度执行一次任务</td></tr><tr><td><code class=" language-php">->yearly();</code></td><td>每年执行一次任务</td></tr><tr><td><code class=" language-php">->timezone('America/New_York');</code></td><td>设置时区</td></tr></tbody></table>这些方法可以合并其它限制条件以生成更精确的调度。例如在某周的某几天运行调度。举个例子，计划一个每周周一的调度：<pre class=" language-php"><code class=" language-php">// 每周一的下午一点钟运行 $schedule->call(function () { // })->weekly()->mondays()->at('13:00'); // 工作日中从早上 8 点钟运行到下午 5 点 $schedule->command('foo') ->weekdays() ->hourly() ->timezone('America/Chicago') ->between('8:00', '17:00');</code></pre>下方列出其它额外限制条件：<table><thead><tr><th>方法</th><th>描述</th></tr></thead><tbody><tr><td><code class=" language-php">->weekdays();</code></td><td>限制任务在工作日</td></tr><tr><td><code class=" language-php">->sundays();</code></td><td>限制任务在星期日</td></tr><tr><td><code class=" language-php">->mondays();</code></td><td>限制任务在星期一</td></tr><tr><td><code class=" language-php">->tuesdays();</code></td><td>限制任务在星期二</td></tr><tr><td><code class=" language-php">->wednesdays();</code></td><td>限制任务在星期三</td></tr><tr><td><code class=" language-php">->thursdays();</code></td><td>限制任务在星期四</td></tr><tr><td><code class=" language-php">->fridays();</code></td><td>限制任务在星期五</td></tr><tr><td><code class=" language-php">->saturdays();</code></td><td>限制任务在星期六</td></tr><tr><td><code class=" language-php">->between($start, $end);</code></td><td>限制任务运行在开始到结束时间范围内</td></tr><tr><td><code class=" language-php">->when(Closure);</code></td><td>限制任务基于一个为真的验证</td></tr></tbody></table><h4>时间范围限制</h4><code class=" language-php">between</code> 方法可以用来限制一天中某个时间范围内：<pre class=" language-php"><code class=" language-php">$schedule->command('reminders:send') ->hourly() ->between('7:00', '22:00');</code></pre>类似的，<code class=" language-php">unlessBetween</code> 方法可以用来排除时间段：<pre class=" language-php"><code class=" language-php">$schedule->command('reminders:send') ->hourly() ->unlessBetween('23:00', '4:00');</code></pre><h4>为真验证限制条件</h4><code class=" language-php">when</code> 方法可以用来判断是否要运行任务，主要基于一个指定的为真验证的运行结果。如果指定的 <code class=" language-php">闭包</code> 返回 <code class=" language-php">true</code>，且没有其它限制条件存在，那么这个任务将会被继续运行。<pre class=" language-php"><code class=" language-php">$schedule->command('emails:send')->daily()->when(function () { return true; });</code></pre><code class=" language-php">skip</code> 是 <code class=" language-php">when</code> 的颠倒意味。<code class=" language-php">skip</code> 方法返回 <code class=" language-php">true</code> 的话，计划就不会运行。<pre class=" language-php"><code class=" language-php">$schedule->command('emails:send')->daily()->skip(function () { return true; });</code></pre>当链式调用了 <code class=" language-php">when</code> 方法时，计划命令只有在所有的 <code class=" language-php">when</code> 条件返回 <code class=" language-php">true</code> 时才运行。<a name="preventing-task-overlaps"></a><h3>避免任务重复</h3>默认情况，即便之前相同的任务主体仍未结束，现有计划任务依旧会被运行。为了避免这个问题，你可以使用 <code class=" language-php">withoutOverlapping</code> 方法：<pre class=" language-php"><code class=" language-php">$schedule->command('emails:send')->withoutOverlapping();</code></pre>在这个例子中，如果没有其它 <code class=" language-php">emails:send</code> <a href="/docs/5.4/artisan">Artisan 命令</a> 在运行的话，此任务将于每分钟被运行一次。当你有些任务运行时间过长，且无法预测出具体所需时间时， <code class=" language-php">withoutOverlapping</code> 方法将会特别有帮助。<a name="maintenance-mode"></a><h3>维护模式</h3>当应用进入 <a href="/docs/5.4/configuration#maintenance-mode">维护模式</a> 时，默认情况下 Laravel 的调度功能将会停止运行。这是因为我们考虑到你可能在维护模式下做一些破坏性的维护工作，我们不想让任务调度对这些工作造成干扰。然而，如果你想强制某个任务在维护模式下运行的话，你可以使用 <code class=" language-php">evenInMaintenanceMode</code> 方法：<pre class=" language-php"><code class=" language-php">$schedule->command('emails:send')->evenInMaintenanceMode();</code></pre><a name="task-output"></a><h2><a href="#task-output">任务输出</a></h2>Laravel 调度器为任务调度输出提供多种便捷方法。首先，通过 <code class=" language-php">sendOutputTo</code> 你可以发送输出到单个文件上以便后续检查：<pre class=" language-php"><code class=" language-php">$schedule->command('emails:send') ->daily() ->sendOutputTo($filePath);</code></pre>如果想将输出附加到指定的文件上，则可以使用 <code class=" language-php">appendOutputTo</code> 方法：<pre class=" language-php"><code class=" language-php">$schedule->command('emails:send') ->daily() ->appendOutputTo($filePath);</code></pre>通过 <code class=" language-php">emailOutputTo</code> 方法，你可以发送输出到你所指定的电子邮件上。注意，你必须先通过 <code class=" language-php">sendOutputTo</code> 方法将其输出到一个文件。同时，在邮件发出之前，你需要先设置 Laravel 的 <a href="/docs/5.4/mail">电子邮件服务</a>:<pre class=" language-php"><code class=" language-php">$schedule->command('foo') ->daily() ->sendOutputTo($filePath) ->emailOutputTo('foo@example.com');</code></pre><blockquote class="has-icon note"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="90px" height="90px" viewBox="0 0 90 90" enable-background="new 0 0 90 90" xml:space="preserve"><path fill="#FFFFFF" d="M45 0C20.1 0 0 20.1 0 45s20.1 45 45 45 45-20.1 45-45S69.9 0 45 0zM45 74.5c-3.6 0-6.5-2.9-6.5-6.5s2.9-6.5 6.5-6.5 6.5 2.9 6.5 6.5S48.6 74.5 45 74.5zM52.1 23.9l-2.5 29.6c0 2.5-2.1 4.6-4.6 4.6 -2.5 0-4.6-2.1-4.6-4.6l-2.5-29.6c-0.1-0.4-0.1-0.7-0.1-1.1 0-4 3.2-7.2 7.2-7.2 4 0 7.2 3.2 7.2 7.2C52.2 23.1 52.2 23.5 52.1 23.9z"></path></svg></div> <code class=" language-php">emailOutputTo</code>，<code class=" language-php">sendOutputTo</code> 和 <code class=" language-php">appendOutputTo</code> 方法只适用于 <code class=" language-php">command</code>方法，不支持 <code class=" language-php">call</code> 方法。</blockquote><a name="task-hooks"></a><h2><a href="#task-hooks">任务钩子</a></h2>通过 <code class=" language-php">before</code> 与 <code class=" language-php">after</code> 方法，你能让特定的代码在任务完成之前及之后运行：<pre class=" language-php"><code class=" language-php">$schedule->command('emails:send') ->daily() ->before(function () { // Task is about to start... }) ->after(function () { // Task is complete... });</code></pre><h4>Ping 网址</h4>通过 <code class=" language-php">pingBefore</code> 与 <code class=" language-php">thenPing</code> 方法，调度器能自动的在一个任务完成之前或之后 ping 一个指定的网址。该方法在你计划的任务进行或完成时，可用来有效的通知一个外部服务，例如 <a href="https://envoyer.io">Laravel Envoyer</a>：<pre class=" language-php"><code class=" language-php">$schedule->command('emails:send') ->daily() ->pingBefore($url) ->thenPing($url);</code></pre>使用 <code class=" language-php">pingBefore($url)</code> 或 <code class=" language-php">thenPing($url)</code> 功能需要 Guzzle HTTP 函数库的支持。可在 <code class=" language-php">composer.json</code> 文件中加入以下代码来安装 Guzzle：<pre class=" language-php"><code class=" language-php">composer require guzzlehttp/guzzle</code></pre></article>