Scheduled tasks

Author: AugustMiller

docs/.vuepress/sets/craft-cms.js

@@ -68,6 +68,7 @@ module.exports = {
             "extend/mail",
             "extend/migrations",
             "extend/models",
+            "extend/scheduling",
             "extend/services",
             "extend/session",
             "extend/templates",

docs/6.x/extend/avenues.md

@@ -127,7 +127,8 @@ Instead of setting up an event listener to, say, register a field type,
 - `HasFrontendAssets` → `$vite`, `$styles`, `$scripts` — Configuration or path maps for various [asset publishing](assets.md) options.
 - `HasListeners` → `$events` — Bind [events](events.md) (keys) to listeners (values).
 - `HasPermissions` → `getPermissions()` (Array) — `CraftCms\Cms\User\Data\Permission` objects, with optional nesting.
-- `HasRoutes` → Loads [routes](http.md) defined in `routes/[web|cp|~~actions~~].php`.
+- `HasRoutes` → Loads [routes](http.md) defined in `routes/[web|cp|actions].php`.
+- `HasScheduling` → `schedule()` — Register [recurring tasks](scheduling.md).
 - `HasSettings` → `$hasCpSettings`, `$hasReadOnlyCpSettings` (Boolean) — Enables automatic routing to a dedicated [settings](config.md) screen in the control panel.
 - `HasTranslations` → `$t9nCategory`, `$sourceLanguage` — Customize the translation category. Defaults to your plugin handle.
 - `HasUtilities` → `$utilities` (Array) — Register utilities.

docs/6.x/extend/queue.md

@@ -12,7 +12,7 @@ use MyOrg\Activity\Reporting\Manager;
 class GenerateReport extends Job
 {
     public function __construct(
-        public int $reportId,
+        public int $templateId,
         public bool $notifyOwner,
     ) {}
 
@@ -21,7 +21,7 @@ class GenerateReport extends Job
         Manager $manager,
     ): void
     {
-        $report = $manager->getReportById($this->reportId);
+        $report = $manager->getTemplateById($this->templateId);
     }
 }
 ```
@@ -50,3 +50,7 @@ A few other changes are worth noting:
 - `ttr` has been renamed `timeout`
 - Job are identified by UUIDs instead of IDs.
 - New kinds of jobs are available to projects that support them: consider implementing [chained jobs](laravel:queues#chains-and-batches), [collision-avoidance](laravel:queues#preventing-job-overlaps), or [parallelization](laravel:queues#job-batching)
+
+## Scheduling
+
+Jobs can also be [executed on a schedule](laravel:scheduling#scheduling-queued-jobs).

docs/6.x/extend/scheduling.md

@@ -0,0 +1,46 @@
+# Scheduled Tasks
+
+Your plugin can register recurring workloads with Laravel’s internal [scheduler](laravel:scheduling).
+
+<!-- more -->
+
+These tasks can be implemented as [commands](laravel:artisan), [jobs](laravel:queues), or plain closures.
+To configure a recurring task, define a `schedule()` method on your plugin’s base class:
+
+```php
+protected function schedule(Schedule $schedule): void
+{
+    // Send a test email every day:
+    $schedule->command('craft:mailer:test')
+        ->daily();
+
+    // Queue a report at the top of every hour:
+    $schedule->job(new GenerateReport(['templateId' => 1234]))
+        ->hourly();
+
+    // Report
+    $schedule->call(function () {
+        Log::info('Scheduler healthy!');
+    })
+        ->everyTenMinutes()
+        ->thenPing(env('UPTIME_KUMA_SERVICE_URL'));
+}
+```
+
+This `$schedule` instance is the same underlying class that Laravel’s documentation uses via a facade, so the APIs are identical.
+Refer to the [scheduling documentation](laravel:scheduling) for a complete list of capabilities and options.
+
+## Running the Schedule
+
+The scheduler requires regular invocation by the host; it does not run automatically.
+A typical CRON task would look something like this:
+
+```
+* * * * * /usr/bin/env php /var/www/html/artisan schedule:run
+```
+
+::: tip
+This expression is compatible with DDEV’s [CRON add-on](https://github.com/ddev/ddev-cron).
+:::
+
+Some projects may not have a reliable schedule runner set up, so it’s important that you mention any reliance on scheduled tasks in your plugin’s installation instructions.