Laravel Queue Management Laravel Package

Getting Started

• Require the package with Composer and confirm you're on 1.0.1 or later — the forget() identifier fix is a correctness (and on MySQL, a data-safety) fix, not just an ergonomics one. Pin ^1.0.1 in composer.json so CI and prod don't resolve 1.0.0.
• No publish step is required for basic use. The package is a thin, developer-facing wrapper over Laravel's failed-job storage and the queue:forget / queue:retry commands, so the first place to look is config/queue.php → failed.driver. Your day-to-day behavior differs materially between database (integer id) and database-uuids (string uuid).
• First use: grab a record from your failed_jobs table (via php artisan queue:failed or a tinker query) and call retry($idOrUuid) / forget($idOrUuid) from tinker. Confirm which column your driver uses before passing anything in.
• First place to look when something misbehaves: the resolved value handed to the underlying Artisan command. Both retry() and forget() ultimately shell out to queue:retry / queue:forget, and nearly every historical bug in this package was an identifier-shape mismatch, not a queue problem.

Implementation Patterns

• Retry from an admin UI or internal tool. Pass the identifier straight from the failed_jobs row you rendered. In 1.0.1+ UUIDs are passed through unchanged, so you no longer need to translate uuid → id yourself before calling retry().

• Forget after retry. A common pattern is a "retry and clear" action: retry($row->uuid); forget($row->uuid);. This is now safe under database-uuids, which previously threw on MySQL and no-op'd silently elsewhere.

• Driver-aware helper. If your app supports both drivers (e.g. local database, prod database-uuids), resolve the identifier once and branch on the driver rather than guessing:

  $key = config('queue.failed.driver') === 'database-uuids'
      ? $job->uuid
      : $job->id;
  

• Bulk cleanup. Chunk over the failed_jobs table and call forget() per row rather than deleting rows directly — going through the package keeps any listener/event behavior and command output intact.

• Artisan wrapper. Expose a small queue:purge-failed --before=... command in your app that delegates to the package; this is the natural seam for adding authorization, audit logging, and "dry run" output before anything is destroyed.

• Queue-scoped operations. When retrying a batch, filter by queue and connection columns first and retry in a loop; the package operates on single identifiers, so fan-out is your responsibility.

Gotchas and Tips

• Upgrade if you're on MySQL and use database-uuids. In 1.0.0, forget() passed the integer id where a UUID was expected. On MySQL that could resolve a different failed job — i.e. delete the wrong record. On other databases it silently deleted nothing. Treat 1.0.0 as unsafe for any forget() path that derived an id from a UUID-keyed row.
• UUID pass-through is now literal. Since 1.0.1, a UUID-shaped input is not looked up by primary key first. This is the fix, but it means you cannot rely on "pass a uuid string, let the package figure out the int id" behavior. Be explicit about which column you're reading.
• Silent no-ops are the failure mode, not exceptions. forget() on a non-matching identifier often just deletes nothing. Always assert on the return value / command output in tests; a green test that only checks "no exception thrown" proves nothing here.
• Debugging identifier bugs: log the exact value and the driver immediately before calling the package, then compare against php artisan queue:failed. If the value isn't in that list, the bug is upstream in your row mapping.
• Test both drivers. A single test suite against SQLite will not catch the MySQL UUID comparison behavior that caused #10/#11. Add a database-uuids variant to your feature tests, ideally against MySQL in CI.
• Extension points: the failed-job model and the driver config are the two seams worth customizing. If you need multi-tenant scoping or soft-deletes on failed jobs, wrap the package rather than forking it — the surface area you'd need to reimplement is small, and you keep the upstream identifier fixes.
• Watch for further UUID/ID handling changes. This area has already produced two bugs in a single patch release; pin the minor version and read the changelog before bumping.