Search by

toreador / flarum-job-queue

List, inspect, requeue and auto-requeue failed database queue jobs from the Flarum admin panel.

Maintainers

Package info

github.com/toreador34/flarum-job-queue

Type:flarum-extension

pkg:composer/toreador/flarum-job-queue

Transparency log

Statistics

Installs: 8

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

Security

Advisories: 0

Aikido package health analysis

v1.0.2 2026-09-01 21:38 UTC

Requires

Requires (Dev)

None

Suggests

None

Provides

None

Conflicts

None

Replaces

None

MIT 66beb7817a9078ad7f9d7f675e5e25aa65c50a0c

  • Toreador

databasequeuejobsrequeueflarumfailed-jobs

Published on Packagist.org on 2026-09-01 21:38 UTC

This package is auto-updated.

Last update: 2026-09-01 21:42:30 UTC

README

GitHub · Packagist

Flarum 1.x admin extension for the flarum/blomstra database queue driver. It lists failed queue jobs, inspects their payload/exception and explains what each job does, allows requeueing them (individually or all at once) and can auto-requeue stale failed jobs via the scheduled task runner — all from the admin panel.

toreador/flarum-job-queue

Installation

composer require toreador/flarum-job-queue

Then enable the extension:

php flarum extension:enable toreador-flarum-job-queue
php flarum cache:clear

Local path install (development): add a path repository and require it: "repositories": [{"type": "path", "url": "path/to/flarum-job-queue"}] then composer require toreador/flarum-job-queue:*.

If you installed from source, rebuild the admin JS bundle with cd js && npm run build (the committed js/dist is used by releases).

What it manages

Flarum's blomstra/database-queue driver stores jobs in two tables that are auto-prefixed with the value from config.php database.prefix (e.g. sjn4F_):

Table Purpose
{prefix}queue_jobs Pending (queued) jobs, processed by the worker
{prefix}queue_failed_jobs Jobs that exhausted their retry count, moved here by the failed-job controller

This extension reads the live prefix from the active database connection, so it works out of the box with any prefix. If you ever need to point it at a different prefix you can override it with the setting toreador-flarum-job-queue.table_prefix.

Admin page

Open Administration → Queue Manager:

  • Stats cards: pending jobs, failed jobs, table names actually in use.
  • Toolbar: search, filter by queue, requeue all failed, clear all failed, auto-refresh toggle.
  • Table: id, uuid, queue, display name, what the job does, attempts/max tries, failed at and per-row actions (requeue, delete, view).
  • The view modal shows the raw payload JSON and the exception text so you can see exactly why the job failed.
  • Requeueing moves the row back into queue_jobs with attempts=0, reserved_at=NULL, available_at/created_at = now. The original id is preserved when free; the uuid is preserved when the jobs table has that column.

Auto-requeue (scheduled)

The extension registers a console command and schedules it every minute:

php flarum queue:failed-jobs:requeue                 # process settings-driven auto-requeue
php flarum queue:failed-jobs:requeue 12 42           # requeue specific failed-job ids

Auto-requeue on schedule is enabled with the admin settings:

  • toreador-flarum-job-queue.auto_requeue — requeue old failed jobs on schedule
  • toreador-flarum-job-queue.auto_requeue_after (minutes) — only jobs older than this are requeued (default 5; 0 disables the age filter)

The scheduled command requeues nothing when auto_requeue is off. Explicit queue:failed-jobs:requeue <ids...> always works.

What the requeue does

Equivalent SQL (assuming prefix sjn4F_, replacing :now with UNIX_TIMESTAMP() on MySQL):

INSERT INTO sjn4F_queue_jobs
    (uuid, queue, payload, attempts, reserved_at, available_at, created_at)
SELECT uuid, queue, payload, 0, NULL,
       :now,                                  -- available_at = now()
       :now                                   -- created_at = now()
FROM sjn4F_queue_failed_jobs
WHERE id = :failedJobId;                      -- or WHERE 1=1 for "requeue all"

DELETE FROM sjn4F_queue_failed_jobs WHERE id = :failedJobId;

Notes (all defensive, this is what the extension actually does):

  • Columns are only touched when they exist on the live table. On installs where the jobs table has no uuid column that write is omitted and a fresh Str::uuid() is used instead.
  • Preserving the original id keeps the job's position: the extension inserts with the original id and lets the database pick a new one if it is taken.
  • All statements run inside a transaction; if the insert fails the failed row is left untouched.

API endpoints

Method Route Purpose
GET /api/queue-manager/jobs Stats + start page of failed jobs
GET /api/queue-manager/jobs/:id Single job detail (payload + exception)
POST /api/queue-manager/jobs/:id/requeue Requeue one failed job
POST /api/queue-manager/jobs/requeue Requeue all (optionally ?queue=)
DELETE /api/queue-manager/jobs/:id Delete one failed job record
POST /api/queue-manager/jobs/clear Delete all (optionally ?queue=)

Requirements

  • PHP 7.4+
  • Flarum ^1.2 (1.x compatibility first; 2.x support planned)
  • blomstra/database-queue (database queue driver) enabled in Flarum
  • Flarum scheduler (or cron running php flarum schedule:run) for the auto-requeue command

About this fork

License

MIT. See LICENSE.