Skip to main content

Recurring jobs

A recurring job runs on a cron schedule and takes no payload. Implement Zeridion\Flare\Worker\RecurringJob and supply a cron expression on the #[FlareJob] attribute.

<?php

use Zeridion\Flare\Worker\FlareJob;
use Zeridion\Flare\Worker\JobContext;
use Zeridion\Flare\Worker\RecurringJob;

#[FlareJob(name: 'NightlyCleanup', cron: '0 3 * * *', queue: 'maintenance', timezone: 'UTC')]
final class NightlyCleanup implements RecurringJob
{
    public function handle(JobContext $ctx): void
    {
        $this->purgeExpiredSessions();
    }
}

Register it like any other job:

$worker->register(NightlyCleanup::class);

How scheduling works​

When the worker starts, it registers the cron schedule with the server. The server owns the schedule and enqueues a run at each cron tick; that run is then delivered to a worker and dispatched to your handle method exactly like a normal job. Your process does not evaluate cron itself.

Timezone​

Always set timezone for non-UTC schedules. The cron expression is evaluated in that timezone, so 0 3 * * * with timezone: 'America/New_York' fires at 3 AM New York time. If you omit it, the server's default timezone applies, which can run the job at the wrong wall-clock time.

The handle method​

The method name is fixed to handle and takes only a JobContext:

public function handle(JobContext $ctx): void;

Returning normally acknowledges success; throwing acknowledges failure (the server decides on retry vs. dead-letter).

Long-running cleanups​

A long recurring job should honour cancellation cooperatively so it can stop promptly on timeout or shutdown:

public function handle(JobContext $ctx): void
{
    foreach ($this->batches() as $batch) {
        if ($ctx->cancellationRequested()) {
            return;
        }
        $this->process($batch);
    }
}

See also​

Last updated on