Skip to content

Installation

This page covers the requirements, installation, database migrations, optional per-backend extensions, the envelope signing key, and the minimal configuration you need to start dispatching and processing jobs. When you are done here, continue with the Quick Start.

Requirements

Requirement Version / Notes
PHP ^8.2 (uses readonly classes, enums-style value objects, first-class callable syntax)
CodeIgniter 4 (codeigniter4/framework)
Composer required to install
ext-pcntl optional, Unix only — enables hard (interrupting) timeouts and graceful worker shutdown

The sync backend (the zero-config default) needs nothing beyond PHP and CodeIgniter. Each other backend has its own optional dependency — see Optional extensions below.

Install

composer require daycry/jobs

The package registers its commands, services and migrations automatically through CodeIgniter's auto-discovery — no manual service registration is required.

Run the migrations

The package ships migrations for the queue table (including its lease columns reserved_at / available_at / owner_token and the max_retries column) and a history table. Run them with the package namespace:

php spark migrate -n "Daycry\Jobs"

This creates the queues table used by the database backend.

Note: Only the database backend strictly requires these tables. The sync backend (the default) does not, but running the migrations anyway is recommended so you can switch backends later without surprises. The table name is configurable via Config\Jobs::$database['table'] (default queues) and the connection group via Config\Jobs::$databaseGroup / Config\Jobs::$database['group'].

Optional: publish the config

To customise the configuration under your application namespace:

php spark jobs:publish

You will be prompted to confirm; answering y creates app/Config/Jobs.php that extends Daycry\Jobs\Config\Jobs. Publishing is optional — the package ships with working defaults (the sync backend, all five handlers registered). Publish when you want to change queues, the default worker, retry/backoff parameters, the per-queue handler allowlist, the signing key or backend-specific settings. See Configuration for every option.

// app/Config/Jobs.php (generated by jobs:publish)
namespace Config;

class Jobs extends \Daycry\Jobs\Config\Jobs
{
    // Override only what you need; everything else inherits package defaults.
}

Optional extensions

Install only what the backend you choose needs:

Backend PHP extension / package How to install
sync none built in (default)
database none (uses the configured CI4 DB connection) run the migrations above
redis ext-redis enable the PECL Redis extension
beanstalk pda/pheanstalk composer require pda/pheanstalk
serviceBus none (uses the CodeIgniter curlrequest service) configure Config\Jobs::$serviceBus

For real, interrupting timeouts and graceful worker shutdown on Unix, install ext-pcntl:

Capability With ext-pcntl Without ext-pcntl
Per-attempt timeout SIGALRM throws and interrupts even CPU-bound code documented soft check (cannot interrupt a blocking call)
Graceful shutdown SIGTERM/SIGINT finish the current cycle then exit the worker still exits, but cannot trap signals mid-loop

Warning: ext-pcntl is CLI-only and unavailable on Windows. On Windows the worker still runs; timeouts fall back to the soft mode and you should bound long-running jobs at the application level. See Concurrency and Configuration ($defaultTimeout, $jobTimeout).

Configure the signing key

Queue envelopes are signed with HMAC-SHA256 so the worker can reject tampered or forged messages. The signer resolves its key in this order:

  1. Config\Jobs::$signingKey (if not null)
  2. env('JOBS_SIGNING_KEY')
  3. the CodeIgniter Config\Encryption::$key

The simplest production setup is an environment variable in your .env:

JOBS_SIGNING_KEY = "a-long-random-secret-shared-by-producers-and-workers"

Warning: If no key can be resolved, the signer operates in insecure pass-through mode (sign() returns '' and verify() returns true) and the worker logs this as critical. For any persistent or remote backend, set a key. The same key must be configured on every process that enqueues and every worker that consumes. See Security.

Minimal configuration

For most setups you only need to set the default backend and the queues. In app/Config/Jobs.php:

namespace Config;

class Jobs extends \Daycry\Jobs\Config\Jobs
{
    // Default backend used by Jobs::backend(), dispatch() and the worker when --backend is omitted.
    public string $worker = 'database';

    // Available queue names. Accepts a comma-separated string or a list<string>.
    public array|string $queues = 'default,reports,emails';
}

The built-in $backends map already wires every backend class, and $handlers registers the five built-in handler keys (command, shell, closure, event, url), so you do not need to repeat them unless you are adding your own.

Note: $worker is the default backend name, not a queue. The default value is sync, which runs jobs inline at dispatch() time. Use database/redis/beanstalk/serviceBus for out-of-process processing.

Verify the install

php spark list

You should see the Jobs command group:

Jobs
  jobs:cronjob:run   Runs jobs based on the schedule; configure it as a crontask to run every minute.
  jobs:publish       Publish the jobs config file.
  jobs:queue:purge   Purge completed/failed jobs from the queue table
  jobs:queue:reap    Reclaim queue messages whose visibility timeout expired.
  jobs:queue:work    Start a v3 queue worker.

Next steps