Skip to main content
Work that can’t finish inside a request happens in one of three places:
  • 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.
The queue lives in 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:
  1. The scheduler runs every task that is due. Each task is claimed with a lease in the scheduled_task table, so two overlapping runs never run the same task twice, and each runs isolated: a failing task is recorded and the others still run.
  2. 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.
This is why cron alone is enough, including on shared hosting. A worker started with app:queue:work under Supervisor or systemd only makes jobs start sooner.
Run cron and workers as the same user as the web server. A process running as root creates cache and upload files the web server can’t overwrite, which shows up later as a cache that won’t clear.
See Initial setup and Background Jobs & Queue for the production configuration.

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, so toArray() returns plain values only and fromArray() 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.
Jobs run at least once. Write handlers so a second run does no harm.

Scheduled tasks

A scheduled task implements Cron\Domain\ScheduledTaskInterface:
Register it with Cron\Infrastructure\Scheduler\TaskCollectionInterface under a stable name, with a translatable label for the admin area:
A run that was missed (cron didn’t run, or ran late) happens once on the next run. Keep 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 the queue.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.

Checking it works

The Status page shows when cron last ran and whether tasks or jobs are failing. Settings → System → Queue shows waiting and failed jobs, workers and every scheduled task.