任務排程

• 簡介
• 定義排程
  • 排程 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' => env('APP_TIMEZONE', 'UTC'),
 
'schedule_timezone' => 'America/Chicago',

防止任務重疊

預設情況下，即使任務的前一個執行個體仍在執行中，排定任務也會執行。為防止這種情況，您可以使用 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 命令來清除這些快取鎖定。這通常僅在由於意外的伺服器問題而導致任務卡住時才需要。

在單一伺服器上執行任務

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

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

use Illuminate\Support\Facades\Schedule;
 
Schedule::command('report:generate')
                ->fridays()
                ->at('17:00')
                ->onOneServer();

命名單一伺服器作業

有時您可能需要排程相同的作業以不同的參數分派，同時仍然指示 Laravel 在單一伺服器上執行每個作業的排列組合。為了實現這一點，您可以透過 name 方法為每個排程定義指派一個唯一的名稱。

Schedule::job(new CheckUptime('https://laravel.dev.org.tw'))
            ->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();

維護模式

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

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

排程群組

當定義具有相似組態的多個排定任務時，您可以使用 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 Forge 之類的服務，該服務可以為您管理 cron 條目。

* * * * * 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('[email protected]');

如果您只想在排定的 Artisan 或系統命令以非零結束代碼終止時才以電子郵件傳送輸出，請使用 emailOutputOnFailure 方法。

Schedule::command('report:generate')
         ->daily()
         ->emailOutputOnFailure('[email protected]');

任務掛鉤

使用 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 執行個體類型提示為您的 Hook 的閉包定義的 $output 引數，在您的 after、onSuccess 或 onFailure Hook 中存取它。

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 在排程過程中會發出各種事件。您可以為以下任何事件定義監聽器。