kinetis / queue-failed-jobs
Retained failed jobs for kinetis/queue — every job the worker gives up on is recorded in a MySQL/Postgres table before the backend deletes it, with commands to list, retry, forget and prune the records.
Requires
- php: ^8.4
- kinetis/database-bridge: ^1.4.3
- kinetis/framework: ^1.24.3
- kinetis/persistence: ^1.4.6
- kinetis/queue: ^1.9.1
- psr/container: ^2.0.2
Requires (Dev)
- infection/infection: ^0.35.0
- kinetis/migrations: ^1.4.3
- kinetis/queue-sql: ^1.6.8
- phpstan/phpstan: ^2.2.8
- phpunit/phpunit: ^13.3.3
- vimeo/psalm: ^7.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
kinetis/queue-failed-jobs
Failed jobs kept in MySQL/Postgres for kinetis/queue, with list, retry, forget and prune commands
Part of Kinetis, a non-blocking PHP framework for API-first applications, developed in the kinetis-dev/kinetis monorepo.
Records every job the kinetis/queue
worker gives up on in a kinetis_failed_jobs table, before the backend
deletes it, for every queue backend and every named queue connection.
Installing the package turns recording on. With it installed,
queue:work depends on the failed-jobs database and stops when that
database refuses a write, leaving the job on its queue.
vendor/bin/kinetis queue:failed --queue=mail vendor/bin/kinetis queue:retry 3f9c0b2a64d14e8f9a0c51d7e2b46a18 vendor/bin/kinetis queue:retry --all --bound vendor/bin/kinetis queue:forget 3f9c0b2a64d14e8f9a0c51d7e2b46a18 vendor/bin/kinetis queue:prune --hours=168
The store needs a table
Copy the stub matching your database into your
kinetis/migrations
migrations/ directory — migrations/<name>/ when the records live on a
named database connection — with a timestamp prefix, and run
vendor/bin/kinetis migrate:
vendor/kinetis/queue-failed-jobs/resources/migrations/create_kinetis_failed_jobs_table.mysql.php.stub
vendor/kinetis/queue-failed-jobs/resources/migrations/create_kinetis_failed_jobs_table.pgsql.php.stub
The table holds each job's arguments in full, #[Sensitive] values
included, because a retry rebuilds the job from them. Give it the access
controls the queue's own storage has. No command prints a sensitive
value.
Configuration
FAILED_JOBS_DB_CONNECTION_NAME=default
The database connection the store uses: the
kinetis/database-bridge
DB_* keys for default, which an unset or blank value selects, and
DB_{NAME}_* for any other name.
Retrying from code
Kinetis\QueueFailedJobs\FailedJobRetrier runs what queue:retry runs,
for application code such as a dashboard. Inject it and call
retry($id), retryMany($ids) or
retryMatching($connection, $queue, $limit); each returns a
RetryResult per record — Retried, NotFound, or Failed with a
reason — and never a job argument:
$result = $retrier->retry('3f9c0b2a64d14e8f9a0c51d7e2b46a18');
What each status means, and which failures are thrown instead, is in Retrying from code.
Delivery
A job the worker gives up on is held by the backend, recorded, or both —
never neither. A crash between recording and deleting, or an
interrupted queue:retry, can leave a duplicate record or push a job
twice, within the queue's at-least-once contract. See
kinetis.dev/docs/queue-failed-jobs.html.
Installation
composer require kinetis/queue-failed-jobs
Requires PHP 8.4+, kinetis/framework, kinetis/queue,
kinetis/persistence, and
kinetis/database-bridge. Full documentation:
kinetis.dev/docs/queue-failed-jobs.html.
License
MIT — see LICENSE.