Migration to v3¶

v3.0 is a major, breaking release. It collapses the previously coexisting architectures into a single clean design. The legacy mutable Job builder, the V1 Scheduler, the performance loggers, the email notification service, and the old CLI commands have been removed. This guide maps the old surface to its v3 replacement.

If you are coming from a v2.0.0-alpha build, the opt-in Daycry\Jobs\V2\ namespace (JobDefinition, JobLease, QueueBackend, LegacyWorkerAdapter, TypedJobHandler) has been promoted to the root namespace and is now the only architecture. LegacyWorkerAdapter is gone — every backend implements QueueBackend natively.

What was removed¶

Removed	Replacement
Mutable `Job` builder + traits (`IdentityTrait`, `StateTrait`, `FrequenciesTrait`, ...)	`Jobs::define()` → fluent `JobBuilder` → immutable `JobDefinition`.
V1 `Scheduler`	`Daycry\Jobs\Cron\Scheduler` registered in `Config\Jobs::init()`.
Handlers extending `Job` (`ClosureJob`, `CommandJob`, `ShellJob`, `UrlJob`, `EventJob`)	Handlers implementing `JobHandlerInterface` (`AbstractJobHandler` / `TypedJobHandler`).
`QueueInterface` + `WorkerInterface` (`watch()`, `removeJob()`)	Single `QueueBackend` contract with lease semantics.
`QueueManager` singleton	`BackendFactory` / `Jobs::backend()`.
Performance loggers (`JobLogger`, file/db handlers), `$logPerformance`, `$log`, `$loggers`	Removed. Use the metrics collector (`Config\Jobs::$metricsCollector`) and your handler's own logging.
`NotificationService` / email notifications, `notifyOnSuccess()` / `notifyOnFailure()`	Removed. Send notifications from your handler or a downstream job.
`JobsLogModel` and the extended logs table	Removed from the runtime. The history table (`$tableName`) and `jobs:queue:purge` remain for the database backend.
`JobLifecycleCoordinator` + `RequeueHelper` retry loop	One attempt in `JobRuntime`; the worker requeues with backoff via `QueueBackend::nack(delay)`.
Callbacks/chaining (`then()`, `catch()`, `finally()`, `chain()`)	Removed. Compose work explicitly (e.g. dispatch a follow-up job from a handler).
`$batchSize` config (never implemented)	Removed.
CLI: `jobs:queue:run`, `jobs:redis:reap-stuck`, `jobs:cronjob:{enable,disable,list,history}`, `jobs:health`	`jobs:queue:work`, `jobs:queue:reap`, `jobs:cronjob:run`, `jobs:queue:purge`.

API mapping¶

Defining and dispatching a job¶

Old (v1):

use Daycry\Jobs\Job;

$job = (new Job('command', 'app:report'))
    ->named('daily-report')
    ->dailyAt('02:00')
    ->maxRetries(3)
    ->enqueue('reports');

v3:

use Daycry\Jobs\Jobs;

Jobs::define('command', 'app:report')
    ->named('daily-report')
    ->dailyAt('02:00')
    ->queue('reports')
    ->maxRetries(3)
    ->dispatch();

dispatch(?string $backend = null) enqueues onto the named backend (or the configured default) and returns the backend-assigned id. toDefinition() materialises an immutable JobDefinition without dispatching.

Builder methods¶

v1	v3
`new Job($handler, $payload)`	`Jobs::define($handler, $payload)`
`->named($n)`	`->named($n)`
`->enqueue($queue)` / `->push()`	`->queue($queue)->dispatch()`
`->maxRetries($n)`	`->maxRetries($n)`
`->priority($p)`	`->priority($p)`
`->timeout($s)`	`->timeout($s)`
`->singleInstance()`	`->singleInstance()`
`->environments(...)`	`->environments(...)`
`->dependsOn(...)`	`->dependsOn(...)`
`->everyMinute()` / `->hourly()` / `->daily()` / `->dailyAt('HH:MM')` / `->weekly()` / `->monthly()` / `->quarterly()` / `->yearly()`	identical helpers on `JobBuilder`
`->notifyOnSuccess()` / `->notifyOnFailure()`	removed (no built-in notifications)
`->then()` / `->catch()` / `->chain()`	removed (compose explicitly)
—	`->idempotencyKey($k)` (new, opt-in)
—	`->enabled()` / `->disable()` (honoured by the cron runner)

Handlers¶

Old handlers extended the Job god-object. v3 handlers implement JobHandlerInterface and receive an immutable JobContext — no scheduling or queue state.

Old (v1):

class MyJob extends \Daycry\Jobs\Job
{
    public function handle($payload)
    {
        // ...
    }
}

v3:

use Daycry\Jobs\Handlers\AbstractJobHandler;
use Daycry\Jobs\Execution\JobContext;

final class MyHandler extends AbstractJobHandler
{
    public function handle(JobContext $ctx): mixed
    {
        $payload = $ctx->payload; // plus $ctx->name, $ctx->queue, $ctx->attempt, $ctx->meta
        // ... business logic; throw to signal failure ...
        return 'done';
    }
}

Register the key in Config\Jobs::$handlers:

public array $handlers = [
    'command' => CommandHandler::class,
    'myhandler' => \App\Jobs\MyHandler::class,
];

For typed payloads, extend TypedJobHandler and declare payloadType(); the payload is rehydrated into your DTO before run() is called.

Scheduling (cron)¶

Old: jobs were registered on the V1 Scheduler. v3 registers them in Config\Jobs::init():

use Daycry\Jobs\Cron\Scheduler;

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

Run the scheduler every minute from system cron:

* * * * * cd /path/to/app && php spark jobs:cronjob:run >> /dev/null 2>&1

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

Resolving a backend directly¶

Old: QueueManager::instance()->get('redis'). v3:

use Daycry\Jobs\Jobs;

$backend = Jobs::backend('redis'); // or Jobs::backend() for the default worker
$id      = $backend->enqueue($definition);

CLI command mapping¶

v1	v3
`jobs:queue:run <queue>`	`jobs:queue:work <queue> [--once] [--max N] [--backend name]`
`jobs:redis:reap-stuck <queue>`	`jobs:queue:reap <queue> [--backend name]` (all backends)
`jobs:cronjob:run`	`jobs:cronjob:run` (now drives the v3 cron runner)
`jobs:cronjob:enable` / `disable` / `list` / `history`	removed — control scheduling via `enabled()`/`disable()` in `init()`
`jobs:health`	removed — use your metrics collector
`jobs:queue:purge`	`jobs:queue:purge` (unchanged; database backend maintenance)

The worker shuts down gracefully on SIGTERM/SIGINT, applies a circuit breaker per backend, and honours per-queue rate limits.

Configuration changes¶

Removed: $logPerformance, $log, $loggers, $filePath, $maxLogsPerJob, $sensitiveKeys, $maxOutputLength, $batchSize, $workers (now $backends), $jobs (now $handlers), and the email/notification settings.
Added: $handlers, $backends, $queueHandlers (per-queue allowlist), $allowedEvents, $allowAllShellCommands, $signingKey, $verifyEnvelopeSignature, $idempotencyTtl, $databaseVisibilityTimeout, $metricsCollector.
Security defaults: ShellHandler is now deny-by-default ($allowedShellCommands = [] rejects everything); EventHandler requires $allowedEvents; envelope signature verification is on by default. See Security for the full model.

See Configuration for the complete, current list, and Concurrency & Resilience for the locking/breaker/rate-limit controls.

Suggested migration steps¶

Replace new Job(...)->enqueue(...) call sites with Jobs::define(...)->queue(...)->dispatch().
Convert each Job subclass into a JobHandlerInterface implementation and register its key in Config\Jobs::$handlers.
Move scheduled-job registration into Config\Jobs::init() using the v3 Scheduler.
Update Config\Jobs: rename $jobs → $handlers, $workers → $backends; add the security allowlists; remove logger/notification/batch settings.
Set JOBS_SIGNING_KEY (or $signingKey) so envelope signing is active in production.
Update crontab/supervisor entries: jobs:queue:run → jobs:queue:work, jobs:redis:reap-stuck → jobs:queue:reap.
Make handlers idempotent; add idempotencyKey() where a duplicate run must be prevented.