- A queued job, run in the background by cron or a worker.
- A scheduled task, run by the scheduler on its own cron expression.
- A provider webhook, when a third party says the work is done.
src/Queue, the scheduler in src/Cron.
What cron does
cron.php runs every minute. It exits without doing anything when the application isn’t installed yet, or while an update is unfinished: its files are unpacked, but the database may not have the new version’s tables yet. Opening the admin area, or running app:update:finalize, finishes the update, and the next cron run goes ahead. The same check sends admin pages to the update page, through PendingUpdateMiddleware.
Otherwise it hands over to Cron\Infrastructure\CronRunner:
- The scheduler runs every task that is due. Each task is claimed with a lease in the
scheduled_tasktable, so two overlapping runs never run the same task twice, and each runs isolated: a failing task is recorded and the others still run. - The queue is worked for about 50 seconds, unless a long-running worker that takes every queue is alive. At most two cron runs work the queue at the same time.
app:queue:work under Supervisor or systemd only makes jobs start sooner.
Jobs
A job is a small message, usually the ids of what to work on, handled like any command:Queue\Domain\JobInterface. Jobs are stored as JSON, sotoArray()returns plain values only andfromArray()rebuilds the job.#[Handler]names the handler, as for commands. The handler loads what it needs, since the data may have changed by the time the job runs, and returns quietly when the record is gone.#[JobOptions]sets how the job is queued and retried:
Dispatch with
Queue\Infrastructure\QueueBus:
QueueBus holds jobs back until the entity manager’s next flush, so a job never runs before the records it refers to are saved, and it is dropped if the flush fails.Scheduled tasks
A scheduled task implementsCron\Domain\ScheduledTaskInterface:
Cron\Infrastructure\Scheduler\TaskCollectionInterface under a stable name, with a translatable label for the admin area:
run() short: it shares the cron run with every other task. Work that is slow or touches many records belongs in jobs, such as one job per subscription that is due.
Each task’s last run, duration and error are shown under Settings → System → Queue → Scheduled tasks, and failures on the Status page.
These are not the Scheduled tasks users create in the app, which have the assistant carry out instructions on a schedule, each run in a conversation of its own. That feature is called a routine in code and lives in
src/Routine, and its runs are started by one scheduler task, routine.dispatch_due, which queues a job for each routine that is due.Core scheduled tasks
Schedules are cron expressions in UTC.cron.event dispatches Cron\Domain\Events\CronEvent for plugins that still listen to it. Core no longer listens to it. See Plugin events and scheduled work.
Queue adapters
The adapter is where waiting jobs are kept, chosen with thequeue.adapter option:
Adapters implement
Queue\Infrastructure\Adapters\QueueAdapterInterface and are registered with QueueAdapterCollectionInterface, so plugins can add more. The Queue Adapters plugin adds Redis, Amazon SQS, Azure Queue Storage and Cloudflare Queues. An adapter that is uninstalled or can’t run falls back to the database.
Workers and commands
Workers send a heartbeat, so the Queue page lists them. They restart on their own after
app:update and after settings are saved, and they exit after --time-limit, --memory or --max-jobs for the process manager to start them again.
A worker started as root refuses to run when the application belongs to another user, unless you pass --allow-root. --cron marks a worker as started by cron rather than kept running, so it isn’t counted as a long-running worker. See Console commands for every option and its default.
Provider webhooks
Some work isn’t scheduled at all: it finishes when a third party says so. Video and image generation at several providers is asynchronous, and the provider calls a dedicated endpoint when the result is ready. Payment providers do the same for cancellations and asynchronous settlements.
See Payment webhooks.