Configuration¶

All settings live in Daycry\Jobs\Config\Jobs. Copy the file into your application (app/Config/Jobs.php, keeping the Config namespace) to override defaults — CodeIgniter's service locator favours the application namespace.

Every property documented below exists in the v3 Config\Jobs. Nothing here is invented.

Handlers¶

Property	Type	Default	Description
`$handlers`	`array<string, class-string>`	`command`, `shell`, `closure`, `event`, `url`	Single source of truth mapping a handler key to a `JobHandlerInterface` class. `HandlerRegistry` resolves keys exclusively from here.
`$queueHandlers`	`array<string, list<string>>`	`[]`	Per-queue allowlist of handler keys. A queue listed here may run only the keys it declares. A queue absent from the map (or with an empty list) imposes no restriction — set it explicitly in production so remote queues cannot invoke `shell`/`command`.

public array $handlers = [
    'command' => CommandHandler::class,
    'shell'   => ShellHandler::class,
    'closure' => ClosureHandler::class,
    'event'   => EventHandler::class,
    'url'     => UrlHandler::class,
];

// Lock the 'reports' queue to the command handler, and 'web' to url/event only.
public array $queueHandlers = [
    'reports' => ['command'],
    'web'     => ['url', 'event'],
];

Handler Security¶

Property	Type	Default	Description
`$allowedShellCommands`	`list<string>`	`[]`	Allowlist of binaries `ShellHandler` may run. Deny-by-default: an empty list rejects all execution. Entries are matched against the candidate via `realpath()`, so `/tmp/echo` cannot impersonate `/usr/bin/echo`.
`$allowAllShellCommands`	`bool`	`false`	Explicit, insecure escape hatch. When `true`, `ShellHandler` runs any binary even with an empty allowlist.
`$allowedEvents`	`list<string>`	`[]`	Allowlist of event names `EventHandler` may trigger. Empty = deny all (secure default).

// ShellHandler is deny-by-default. Allow specific absolute paths:
public array $allowedShellCommands = ['/usr/bin/ls', '/usr/bin/git'];

// EventHandler only fires events you explicitly permit:
public array $allowedEvents = ['user.registered', 'cache.warm'];

ShellHandler executes through proc_open() with an argv array — never /bin/sh -c — so shell metacharacters carry no attack surface. UrlHandler is SSRF-hardened (http/https only, private/ reserved IPs rejected, SSL verification forced on, redirects disabled). See Security for the full handler-security model.

Envelope Signing¶

Property	Type	Default	Description
`$signingKey`	`?string`	`null`	HMAC-SHA256 key used to sign queue envelopes. When `null`, the signer falls back to `env('JOBS_SIGNING_KEY')` and then to the CodeIgniter `Encryption` key. If no key resolves, signing/verification operate in insecure pass-through mode (logged as `critical`).
`$verifyEnvelopeSignature`	`bool`	`true`	When `true`, the worker rejects messages whose HMAC signature is missing or invalid (when a key is available). Set `false` only for trusted, private backends.

The signature is computed over the immutable identity fields only (job, payload, queue, priority, maxRetries, name, identifier); the mutable attempts/schedule are excluded so the signature survives a requeue. See Security for the key-resolution chain, verification path, and threat model.

Idempotency¶

Property	Type	Default	Description
`$idempotencyTtl`	`int`	`86400`	TTL (seconds) for idempotency keys stored by `IdempotencyGuard`.

Idempotency is opt-in per job via JobBuilder::idempotencyKey(). See Retries.

Rate Limiting¶

Property	Type	Default	Description
`$queueRateLimits`	`array<string, int>`	`[]`	Maximum jobs processed per minute per queue. `0` or missing = unlimited. The worker skips a cycle (logging `[Rate Limited]`) when the limit is reached.

public array $queueRateLimits = [
    'high_priority' => 100,
    'default'       => 50,
];

See Concurrency & Resilience for the rate limiter, circuit breaker and single-instance locking in detail.

Dead Letter Queue¶

Property	Type	Default	Description
`$deadLetterQueue`	`?string`	`null`	Queue name used by the opt-in `DeadLetterQueue::store()` helper (a manual, app-level facility). The worker itself does not consult this value — on exhausted retries it calls `backend->abandon()`, which settles natively (Beanstalk bury, database row marked `failed`, Redis drop) and logs a `critical` entry. To actually route a failed job to this queue you must call `DeadLetterQueue::store()` yourself.

Timeouts¶

Property	Type	Default	Description
`$jobTimeout`	`int`	`300`	Maximum execution time per job in seconds (`0` = unlimited). May be overridden per job.
`$defaultTimeout`	`?int`	`null`	Default per-attempt timeout applied to jobs that do not declare their own via `JobBuilder::timeout()`. `null` disables the global timeout.

The runtime enforces the per-job timeout if set, otherwise $defaultTimeout. When PHP pcntl is available the timeout interrupts the running job (a SIGALRM handler that throws); otherwise it degrades to a soft post-hoc check that cannot abort a runaway job.

Worker Behaviour¶

Property	Type	Default	Description
`$pollInterval`	`int`	`5`	Seconds the worker sleeps after an empty/rate-limited/circuit-open/error cycle before polling again.
`$blockingFetch`	`bool`	`false`	Reserved — not yet wired into the shipped worker; has no effect. The worker always fetches non-blocking (Beanstalk uses a hardcoded `reserveWithTimeout(5)`; Redis uses non-blocking `rpoplpush`).
`$blockingFetchTimeout`	`int`	`5`	Reserved — not yet wired into the shipped worker; has no effect. (Beanstalk's reserve timeout is hardcoded to 5s, not driven by this value.)
`$circuitBreakerThreshold`	`int`	`5`	Consecutive backend failures before the circuit opens.
`$circuitBreakerCooldown`	`int`	`60`	Seconds the circuit stays open before the worker retries the backend.

Reaper / Visibility¶

Property	Type	Default	Description
`$redisProcessingVisibilityTimeout`	`int`	`300`	Visibility timeout (seconds) the Redis backend reaper uses to decide when an in-flight job belongs to a crashed worker and must be returned to the waiting list.
`$databaseVisibilityTimeout`	`int`	`300`	Visibility timeout (seconds) the database backend reaper uses to return an `in_progress` row to `pending`. Must exceed the maximum expected job runtime to avoid reclaiming live jobs.
`$serviceBusLockTimeout`	`int`	`60`	Peek-lock timeout (seconds) requested when locking Service Bus messages. Must be ≥ the maximum job runtime, otherwise the broker may redeliver mid-execution.

These are used by jobs:queue:reap. Beanstalk and Service Bus recover stalled work natively.

Retry / Backoff¶

Property	Type	Default	Description
`$retryBackoffStrategy`	`string`	`none`	One of `none`, `fixed`, `exponential`.
`$retryBackoffBase`	`int`	`5`	Base delay (seconds) used to compute the first retry delay.
`$retryBackoffMultiplier`	`float`	`2.0`	Multiplier for the exponential strategy: `delay = base * multiplier^(attempt-2)`.
`$retryBackoffMax`	`int`	`300`	Upper cap (seconds) on any computed delay.
`$retryBackoffJitter`	`bool`	`true`	Add ±15% random jitter to the computed delay (exponential strategy).

See Retries & Backoff for the full model.

Queues & Backends¶

Property	Type	Default	Description
`$queues`	`list<string>\\|string`	`'default,dummy'`	Comma list or array of available queue names. The first entry is the worker's default when no queue is given.
`$worker`	`string`	`'sync'`	Default backend key (must exist in `$backends`). Resolved by `BackendFactory`.
`$backends`	`array<string, class-string>`	`sync`, `database`, `redis`, `beanstalk`, `serviceBus`	Single source of truth mapping a backend name to a `QueueBackend` class. Used by the worker, the cron runner and `BackendFactory`.

public array $backends = [
    'sync'       => SyncBackend::class,
    'database'   => DatabaseBackend::class,
    'redis'      => RedisBackend::class,
    'beanstalk'  => BeanstalkBackend::class,
    'serviceBus' => ServiceBusBackend::class,
];

public string $worker = 'database';

Backend-specific Settings¶

Database / history table¶

Property	Type	Default	Description
`$database`	`array{group: ?string, table: string}`	`['group' => null, 'table' => 'queues']`	Connection group and table for the database queue backend.
`$databaseGroup`	`?string`	`null`	Connection group used by the Jobs migrations (`null` = default group).
`$tableName`	`string`	`'jobs'`	Name of the table created by the Jobs history migration.

Redis¶

Relies on ext-redis; host/port are taken from the CodeIgniter Redis configuration / environment.

Beanstalk¶

Property	Type	Default
`$beanstalk['host']`	`string`	`127.0.0.1`
`$beanstalk['port']`	`int`	`11300`

Azure Service Bus¶

Property	Type	Description
`$serviceBus['url']`	`string`	Full queue endpoint, e.g. `https://<namespace>.servicebus.windows.net/<queue>`.
`$serviceBus['issuer']`	`string`	SAS key name.
`$serviceBus['secret']`	`string`	SAS key value — prefer `env('SERVICEBUS_SECRET')`.

Metrics¶

Property	Type	Default	Description
`$metricsCollector`	`?string`	`InMemoryMetricsCollector::class`	FQCN of a `MetricsCollectorInterface` implementation. `null` disables metrics (all increment/observe calls no-op). The in-memory default is fine for local/dev but not for production scraping.

Scheduled jobs: `init()`¶

Config\Jobs::init(Scheduler $scheduler) is called by jobs:cronjob:run before evaluating due definitions. Register scheduled jobs on the fluent Scheduler here:

public function init(Scheduler $scheduler): void
{
    $scheduler->define('command', 'app:report')
        ->named('daily-report')
        ->dailyAt('02:00')
        ->queue('reports')
        ->maxRetries(3);

    $scheduler->define('closure', static fn () => cache()->clean())
        ->named('cache-clean')
        ->everyMinute();
}

Definitions that declare a queue() are enqueued; the rest run inline. The runner honours enabled()/environments() and executes in topological order of dependsOn().

Minimal example¶

$cfg                       = config('Jobs');
$cfg->worker               = 'redis';
$cfg->queues               = 'default,reports';
$cfg->signingKey           = env('JOBS_SIGNING_KEY');
$cfg->retryBackoffStrategy = 'exponential';
$cfg->retryBackoffBase     = 3;
$cfg->retryBackoffMax      = 180;
$cfg->deadLetterQueue      = 'failed_jobs';