任務調度 · 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>