# 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](quickstart.md).

---

## 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](#optional-extensions) below.

---

## Install

```bash
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:

```bash
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:

```bash
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](CONFIGURATION.md) for every option.

```php
// 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](concurrency.md) and [Configuration](CONFIGURATION.md) (`$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`:

```dotenv
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](security.md).

---

## Minimal configuration

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

```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

```bash
php spark list
```

You should see the `Jobs` command group:

```text
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

- [Quick Start](quickstart.md) — define a handler, dispatch, run a worker, schedule a cron job.
- [Architecture](ARCHITECTURE.md) — how the pieces fit together.
- [Queues & Workers](QUEUES.md) — the backends in depth.
- [Configuration](CONFIGURATION.md) — every option in `Config\Jobs`.