任務排程

• 簡介
• 定義排程
  • 排程 Artisan 命令
  • 排程佇列任務
  • 排程 Shell 命令
  • 排程頻率選項
  • 時區
  • 防止任務重疊
  • 在單一伺服器上執行任務
  • 背景任務
  • 維護模式
  • 暫停排程任務
  • 排程群組
• 執行排程器
  • 小於一分鐘的排程任務
  • 在本機執行排程器
• 任務輸出
• 任務鉤子
• 事件

簡介

在過去，您可能需要為伺服器上需要排程的每個任務撰寫 cron 配置項目。然而，這很快就會變得麻煩，因為您的任務排程不再受版本控制，而且您必須透過 SSH 登入伺服器才能查看現有的 cron 項目或新增額外項目。

Laravel 的命令排程器提供了一種管理伺服器上排程任務的新方法。排程器允許您在 Laravel 應用程式中流暢且明確地定義命令排程。使用排程器時，您的伺服器只需要一個 cron 項目。任務排程通常定義在應用程式的 routes/console.php 檔案中。

定義排程

您可以在應用程式的 routes/console.php 檔案中定義所有排程任務。讓我們先來看一個範例。在此範例中，我們將排程一個閉包在每天午夜執行。在閉包中，我們將執行一個資料庫查詢來清理一個資料表：

<?php

use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Schedule;

Schedule::call(function () {
    DB::table('recent_users')->delete();
})->daily();

除了使用閉包進行排程外，您還可以排程可呼叫物件。可呼叫物件是包含 __invoke 方法的簡單 PHP 類別：

Schedule::call(new DeleteRecentUsers)->daily();

如果您更傾向將 routes/console.php 檔案保留僅用於命令定義，可以在應用程式的 bootstrap/app.php 檔案中使用 withSchedule 方法來定義排程任務。此方法接收一個閉包，該閉包會取得一個排程器實例：

use Illuminate\Console\Scheduling\Schedule;

->withSchedule(function (Schedule $schedule) {
    $schedule->call(new DeleteRecentUsers)->daily();
})

如果您想查看排程任務及其預定執行時間的概覽，可以使用 schedule:list Artisan 命令：

php artisan schedule:list

排程 Artisan 命令

除了排程閉包外，您還可以排程 Artisan 命令和系統命令。例如，您可以使用 command 方法來排程 Artisan 命令，可以使用命令名稱或類別。

使用命令類別名稱排程 Artisan 命令時，您可以傳遞一個額外的命令列引數陣列，這些引數將在命令被呼叫時提供給它：

use App\Console\Commands\SendEmailsCommand;
use Illuminate\Support\Facades\Schedule;

Schedule::command('emails:send Taylor --force')->daily();

Schedule::command(SendEmailsCommand::class, ['Taylor', '--force'])->daily();

排程 Artisan 閉包命令

如果您想排程一個由閉包定義的 Artisan 命令，可以在命令定義後鏈式呼叫排程相關方法：

Artisan::command('delete:recent-users', function () {
    DB::table('recent_users')->delete();
})->purpose('Delete recent users')->daily();

如果您需要將引數傳遞給閉包命令，可以將它們提供給 schedule 方法：

Artisan::command('emails:send {user} {--force}', function ($user) {
    // ...
})->purpose('Send emails to the specified user')->schedule(['Taylor', '--force'])->daily();

排程佇列任務

job 方法可用於排程佇列任務。此方法提供了一種便捷的方式來排程佇列任務，而無需使用 call 方法定義閉包來將任務加入佇列：

use App\Jobs\Heartbeat;
use Illuminate\Support\Facades\Schedule;

Schedule::job(new Heartbeat)->everyFiveMinutes();

job 方法可接受可選的第二個和第三個參數，用於指定應使用的佇列名稱和佇列連線：

use App\Jobs\Heartbeat;
use Illuminate\Support\Facades\Schedule;

// Dispatch the job to the "heartbeats" queue on the "sqs" connection...
Schedule::job(new Heartbeat, 'heartbeats', 'sqs')->everyFiveMinutes();

排程 Shell 命令

exec 方法可用於向作業系統發出命令：

use Illuminate\Support\Facades\Schedule;

Schedule::exec('node /home/forge/script.js')->daily();

排程頻率選項

我們已經看過一些如何將任務配置為在指定間隔執行的範例。但是，還有更多任務排程頻率可以指派給任務：

這些方法可以與額外的約束條件結合，以建立更精細的排程，僅在特定日期執行。例如，您可以排程一個命令在每週一執行：

use Illuminate\Support\Facades\Schedule;

// Run once per week on Monday at 1 PM...
Schedule::call(function () {
    // ...
})->weekly()->mondays()->at('13:00');

// Run hourly from 8 AM to 5 PM on weekdays...
Schedule::command('foo')
    ->weekdays()
    ->hourly()
    ->timezone('America/Chicago')
    ->between('8:00', '17:00');

以下是其他排程約束條件的列表：

日期約束

days 方法可用於將任務的執行限制為一週中的特定日期。例如，您可以排程一個命令在週日和週三每小時執行：

use Illuminate\Support\Facades\Schedule;

Schedule::command('emails:send')
    ->hourly()
    ->days([0, 3]);

或者，您可以在定義任務應執行的日期時使用 Illuminate\Console\Scheduling\Schedule 類別中可用的常數：

use Illuminate\Support\Facades;
use Illuminate\Console\Scheduling\Schedule;

Facades\Schedule::command('emails:send')
    ->hourly()
    ->days([Schedule::SUNDAY, Schedule::WEDNESDAY]);

時間區間約束

between 方法可用於根據一天中的時間限制任務的執行：

Schedule::command('emails:send')
    ->hourly()
    ->between('7:00', '22:00');

同樣地，unlessBetween 方法可用於排除任務在特定時間區間內執行：

Schedule::command('emails: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 方法可用於僅在給定環境中執行任務（由 APP_ENV 環境變數定義）：

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

時區

使用 timezone 方法，您可以指定排程任務的時間應在給定的時區內解釋：

use Illuminate\Support\Facades\Schedule;

Schedule::command('report:generate')
    ->timezone('America/New_York')
    ->at('2:00')

如果您反覆為所有排程任務指派相同的時區，可以透過在應用程式的 app 配置檔中定義 schedule_timezone 選項來指定應分配給所有排程的時區：

'timezone' => 'UTC',

'schedule_timezone' => 'America/Chicago',

[!WARNING] 請記住，某些時區會使用夏令時間。當夏令時間變更發生時，您的排程任務可能會執行兩次，甚至完全不執行。因此，我們建議盡可能避免使用時區排程。

防止任務重疊

預設情況下，即使任務的前一個實例仍在執行，排程任務仍然會執行。為了防止這種情況，您可以使用 withoutOverlapping 方法：

use Illuminate\Support\Facades\Schedule;

Schedule::command('emails:send')->withoutOverlapping();

在此範例中，如果 emails:send Artisan 命令尚未在執行，它將每分鐘執行一次。withoutOverlapping 方法對於執行時間變化很大的任務特別有用，因為您無法準確預測給定任務需要多長時間。

如果需要，您可以指定「防止重疊」鎖定過期前必須經過的分鐘數。預設情況下，鎖定將在 24 小時後過期：

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

在幕後，withoutOverlapping 方法使用應用程式的快取來取得鎖定。如有必要，您可以使用 schedule:clear-cache Artisan 命令清除這些快取鎖定。這通常僅在任務因意外的伺服器問題而卡住時才需要。

在單一伺服器上執行任務

[!WARNING] 要使用此功能，您的應用程式必須使用 database、memcached、dynamodb 或 redis 快取驅動程式作為應用程式的預設快取驅動程式。此外，所有伺服器必須與同一個中央快取伺服器通訊。

如果應用程式的排程器在多個伺服器上執行，您可以將排程任務限制為僅在單一伺服器上執行。例如，假設您有一個排程任務，每週五晚上產生一份新報告。如果任務排程器在三台工作伺服器上執行，則排程任務將在所有三台伺服器上執行並產生三次報告。這樣不好！

要指示任務僅在一個伺服器上執行，請在定義排程任務時使用 onOneServer 方法。第一個取得任務的伺服器將在任務上取得原子鎖定，以防止其他伺服器同時執行相同的任務：

use Illuminate\Support\Facades\Schedule;

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

您可以使用 useCache 方法來自訂排程器用於取得單一伺服器任務所需原子鎖定的快取儲存：

Schedule::useCache('database');

命名單一伺服器任務

有時您可能需要排程同一個任務使用不同的參數分發，同時仍指示 Laravel 在單一伺服器上執行每個任務變體。為此，您可以透過 name 方法為每個排程定義指派一個唯一的名稱：

Schedule::job(new CheckUptime('https://laravel.com'))
    ->name('check_uptime:laravel.com')
    ->everyFiveMinutes()
    ->onOneServer();

Schedule::job(new CheckUptime('https://vapor.laravel.com'))
    ->name('check_uptime:vapor.laravel.com')
    ->everyFiveMinutes()
    ->onOneServer();

同樣地，如果排程的閉包打算在單一伺服器上執行，則必須為其指派一個名稱：

Schedule::call(fn () => User::resetApiRequestCount())
    ->name('reset-api-request-count')
    ->daily()
    ->onOneServer();

背景任務

預設情況下，在同一時間排程的多個任務將根據它們在 schedule 方法中的定義順序依序執行。如果您有長時間執行的任務，這可能會導致後續任務比預期晚很多才開始。如果您希望任務在背景執行以便它們可以同時執行，可以使用 runInBackground 方法：

use Illuminate\Support\Facades\Schedule;

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

[!WARNING] runInBackground 方法僅在透過 command 和 exec 方法排程任務時才能使用。

維護模式

當應用程式處於維護模式時，您的排程任務將不會執行，因為我們不希望您的任務干擾您可能正在伺服器上進行的未完成維護。但是，如果您想強制任務即使在維護模式下也執行，可以在定義任務時呼叫 evenInMaintenanceMode 方法：

Schedule::command('emails:send')->evenInMaintenanceMode();

暫停排程任務

您可以使用 schedule:pause Artisan 命令暫時暫停排程任務的處理，而無需更改已部署的程式碼：

php artisan schedule:pause

排程器暫停期間，將不會執行任何排程任務。您可以使用 schedule:continue 命令恢復排程任務的處理：

php artisan schedule:continue

如果某個任務在排程器暫停時仍應執行，可以使用 evenWhenPaused 方法標記它：

Schedule::command('emails:send')->evenWhenPaused();

排程群組

在定義具有相似配置的多個排程任務時，您可以使用 Laravel 的任務分組功能來避免為每個任務重複相同的設定。分組任務可以簡化程式碼並確保相關任務之間的一致性。

要建立一個排程任務群組，請呼叫所需的任務配置方法，然後接著呼叫 group 方法。group 方法接受一個閉包，該閉包負責定義共享指定配置的任務：

use Illuminate\Support\Facades\Schedule;

Schedule::daily()
    ->onOneServer()
    ->timezone('America/New_York')
    ->group(function () {
        Schedule::command('emails:send --force');
        Schedule::command('emails:prune');
    });

執行排程器

現在我們已經學會如何定義排程任務，讓我們討論如何在伺服器上實際執行它們。schedule:run Artisan 命令將評估所有排程任務，並根據伺服器的目前時間決定它們是否需要執行。

因此，使用 Laravel 的排程器時，我們只需要在伺服器上新增一個 cron 配置項目，該項目每分鐘執行 schedule:run 命令。如果您不知道如何在伺服器上新增 cron 項目，請考慮使用像 Laravel Cloud 這樣的受管平台，它可以為您管理排程任務的執行：

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

小於一分鐘的排程任務

在大多數作業系統上，cron 任務被限制為最多每分鐘執行一次。但是，Laravel 的排程器允許您以更頻繁的間隔排程任務，甚至可以頻繁到每秒一次：

use Illuminate\Support\Facades\Schedule;

Schedule::call(function () {
    DB::table('recent_users')->delete();
})->everySecond();

當應用程式中定義了小於一分鐘的任務時，schedule:run 命令將繼續執行直到目前分鐘結束，而不是立即退出。這允許命令在整個分鐘內呼叫所有需要的小於一分鐘的任務。

由於執行時間超出預期的小於一分鐘任務可能會延遲後續小於一分鐘任務的執行，建議所有小於一分鐘的任務分發佇列任務或背景命令來處理實際的任務處理：

use App\Jobs\DeleteRecentUsers;

Schedule::job(new DeleteRecentUsers)->everyTenSeconds();

Schedule::command('users:delete')->everyTenSeconds()->runInBackground();

中斷小於一分鐘的任務

由於當定義了小於一分鐘的任務時，schedule:run 命令會在呼叫的整個分鐘內執行，因此在部署應用程式時有時需要中斷該命令。否則，已經在執行的 schedule:run 命令實例將繼續使用應用程式先前部署的程式碼，直到目前分鐘結束。

要中斷正在進行中的 schedule:run 呼叫，可以在應用程式的部署腳本中加入 schedule:interrupt 命令。此命令應在應用程式部署完成後呼叫：

php artisan schedule:interrupt

在本機執行排程器

通常，您不會在本地開發機器上新增排程器 cron 項目。相反，您可以使用 schedule:work Artisan 命令。此命令將在前景執行，並每分鐘呼叫排程器，直到您終止該命令。當定義了小於一分鐘的任務時，排程器將在每分鐘內繼續執行以處理這些任務：

php artisan schedule:work

任務輸出

Laravel 排程器提供了幾種方便的方法來處理排程任務產生的輸出。首先，使用 sendOutputTo 方法，您可以將輸出傳送到檔案以供稍後檢查：

use Illuminate\Support\Facades\Schedule;

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

如果您想將輸出附加到給定檔案，可以使用 appendOutputTo 方法：

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

使用 emailOutputTo 方法，您可以將輸出寄送到您選擇的電子郵件地址。在寄送任務輸出之前，您應該先配置 Laravel 的郵件服務：

Schedule::command('report:generate')
    ->daily()
    ->sendOutputTo($filePath)
    ->emailOutputTo('taylor@example.com');

如果您只想在排程的 Artisan 或系統命令以非零退出碼終止時才寄送輸出，請使用 emailOutputOnFailure 方法：

Schedule::command('report:generate')
    ->daily()
    ->emailOutputOnFailure('taylor@example.com');

[!WARNING] emailOutputTo、emailOutputOnFailure、sendOutputTo 和 appendOutputTo 方法僅適用於 command 和 exec 方法。

任務鉤子

使用 before 和 after 方法，您可以指定在排程任務執行之前和之後要執行的程式碼：

use Illuminate\Support\Facades\Schedule;

Schedule::command('emails:send')
    ->daily()
    ->before(function () {
        // The task is about to execute...
    })
    ->after(function () {
        // The task has executed...
    });

onSuccess 和 onFailure 方法允許您指定在排程任務成功或失敗時要執行的程式碼。失敗表示排程的 Artisan 或系統命令以非零退出碼終止：

Schedule::command('emails:send')
    ->daily()
    ->onSuccess(function () {
        // The task succeeded...
    })
    ->onFailure(function () {
        // The task failed...
    });

如果您的命令有可用輸出，您可以透過在鉤子閉包定義中將 Illuminate\Support\Stringable 實例類型提示為 $output 參數，在 after、onSuccess 或 onFailure 鉤子中存取它：

use Illuminate\Support\Stringable;

Schedule::command('emails:send')
    ->daily()
    ->onSuccess(function (Stringable $output) {
        // The task succeeded...
    })
    ->onFailure(function (Stringable $output) {
        // The task failed...
    });

Ping URL

使用 pingBefore 和 thenPing 方法，排程器可以在任務執行之前或之後自動 ping 一個給定的 URL。此方法對於通知外部服務（如 Envoyer）您的排程任務已開始或已完成執行非常有用：

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

pingOnSuccess 和 pingOnFailure 方法可用於僅在任務成功或失敗時 ping 一個給定的 URL。失敗表示排程的 Artisan 或系統命令以非零退出碼終止：

Schedule::command('emails:send')
    ->daily()
    ->pingOnSuccess($successUrl)
    ->pingOnFailure($failureUrl);

pingBeforeIf、thenPingIf、pingOnSuccessIf 和 pingOnFailureIf 方法可用於僅在給定條件為 true 時 ping 一個給定的 URL：

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

Schedule::command('emails:send')
    ->daily()
    ->pingOnSuccessIf($condition, $successUrl)
    ->pingOnFailureIf($condition, $failureUrl);

事件

Laravel 在排程過程中會分發多種事件。您可以為以下任何事件定義監聽器：