Job context

Every job's handle method receives a Zeridion\Flare\Worker\JobContext. It carries the job's metadata, lets you report progress, exposes the cooperative cancellation handle, and provides a logger pre-bound with this job's identity. You never construct it yourself — the worker provides it.

Metadata

Property	Type	Description
$ctx->jobId	string	Unique id for this execution. Use it as your idempotency key.
$ctx->attempt	int	1-based attempt number.
$ctx->maxAttempts	int	Configured maximum attempts.
$ctx->jobType	string	The job's wire type.
$ctx->enqueuedAt	string	When the job was originally enqueued (RFC-3339). Parse defensively.

Reporting progress

$ctx->reportProgress(0.5); // halfway

Progress is a value from 0.0 to 1.0 and surfaces on the dashboard. The reported value rides the next heartbeat — calling reportProgress does not itself make a network request. Values are clamped (a value above 1 becomes 1); 0, negative, NaN, and infinite values are ignored. The most recent valid value wins.

Cancellation

Cancellation is cooperative — the worker cannot forcibly interrupt a running handler, so a long-running job must check the handle and stop on its own.

public function handle(mixed $payload, JobContext $ctx): void
{
    foreach ($this->workItems() as $item) {
        if ($ctx->cancellationRequested()) {
            return; // stop promptly
        }
        $this->process($item);
    }
}

Method	Description
$ctx->cancellationRequested(): bool	Whether cancellation (timeout, server cancel, or shutdown) was requested.
$ctx->throwIfCancelled(): void	Throws if cancellation was requested — a convenient way to bail out.

A cancelled job is acknowledged as failed. A handler that ignores the handle and never yields keeps running until the server reclaims the job.

Logging

$ctx->logger()->log('info', 'sending email', ['email' => $payload['email']]);

The logger is pre-bound with the job's id, type, and attempt, so your handler's log lines automatically carry the same correlation fields the worker emits. Avoid logging raw payloads or secrets.

See also

• Payload jobs
• Recurring jobs
• Worker overview — heartbeats, cancellation, and at-least-once delivery