Laravel Laravel Package

Getting Started

v1.6.0 is a minor bump from v1.5.1, so under semver you should expect additive, backwards-compatible changes — but the release notes here contain only a compare link, no prose. Treat https://github.com/BabelQueue/laravel/compare/v1.5.1...v1.6.0 as the source of truth and skim the commit/PR list before bumping. If you are already on 1.5.x, budget a patch-window upgrade rather than a migration project; if you are coming from 1.4 or earlier, walk the intermediate compare links too.

Minimal adoption path:

composer require babelqueue/laravel
php artisan vendor:publish --tag=babelqueue-config

Then set the connection in .env and clear caches:

php artisan config:clear
php artisan queue:restart   # long-lived workers must be recycled

Where to look first, in this order:

1. config/babelqueue.php — the published config is the real API surface. Every knob you will need in production lives here, and it is the file most likely to gain or change keys in a minor release.
2. The package service provider — it tells you what is bound into the container and what is registered with Laravel's QueueManager. Anything registered there is meant to be swapped in tests.
3. tests/ or examples/ in the repo — for a queue package these are almost always the most accurate documentation of intended usage.

First use case: take one existing, low-risk ShouldQueue job and route it through the package's connection. Run it locally against the sync or database driver first so you can watch the full lifecycle (dispatch → process → fail → retry) without a broker in the way. Confirm the job lands in failed_jobs when you deliberately throw, then queue:retry. That single loop exercises 90% of the integration surface before you touch anything shared.

Implementation Patterns

Route through the queue manager, not around it. The package should be registered as a queue connection so that QUEUE_CONNECTION=babelqueue works and per-job overrides remain possible:

class SendInvoice implements ShouldQueue
{
    public function viaConnection(): string { return 'babelqueue'; }
    public function viaQueue(): string { return 'billing'; }
}

Keeping this indirection means you can fall back to database in local dev and in CI without touching job classes.

Dispatch from the transaction boundary, not inside it. The most common production bug in queue integrations is dispatching a job that reads a row that hasn't committed yet. Use afterCommit() (or DB::afterCommit) on any dispatch that is downstream of a write:

SendInvoice::dispatch($invoice)->afterCommit();

Push cross-cutting concerns into job middleware, not into every job's handle(). Rate limiting, tenant scoping, structured logging, and metrics belong there — it is the cleanest place to hook package behaviour you don't control, and it survives package upgrades better than subclassing internals.

Keep worker pools separated by queue. Run distinct supervisor programs per queue name so a slow billing queue can't starve notifications. Size --tries, --timeout, and --max-time per pool rather than globally.

Testing pattern. Fake the queue for unit tests (Queue::fake() + assertPushed), and run a thin integration suite against the real driver in CI. If the package ships its own fake or assertion helpers, prefer those over raw Queue::fake() — they tend to assert payload shape, which is where regressions actually hide.

Observability. Listen to Laravel's JobProcessing / JobProcessed / JobFailed events rather than adding logging inside jobs. One listener gives you metrics across every job in the app, including ones you didn't write. If you run Redis and Horizon, verify Horizon's introspection still works through the package's connection before rolling it out broadly.

Gotchas and Tips

• Workers are long-lived; your code is not. After every deploy: php artisan queue:restart. Every "the fix didn't work" report on a queue package traces back to this. Wire it into your deploy script or a php artisan deploy command.
• retry_after must exceed worker --timeout. If it doesn't, a slow job gets picked up by a second worker while the first is still running — silent duplicate execution, no error, no failed job. This is the single most common config mistake.
• At-least-once, not exactly-once. Design handlers to be idempotent. Use a unique constraint, a processed-events table, or WithoutOverlapping middleware rather than assuming single execution.
• Payloads must serialize. No closures in job properties, no raw Eloquent models without SerializesModels, and watch payload size — brokers have message limits and a fat model serialization will fail at dispatch time, not at handle time.
• env() outside config files is a trap. If the package reads env vars directly rather than via config(), config:cache will produce surprising behaviour in production. Verify by running php artisan config:cache locally before deploying.
• Diff the published config on upgrade. Minor releases may add keys with defaults that differ from "unset". Re-publish to a temp path and diff against your committed config/babelqueue.php rather than overwriting.
• Debugging failed jobs: php artisan queue:failed, then queue:retry {id} or queue:forget. Exception messages in the failed_jobs table are truncated — pull full stack traces from your log channel, not the DB.
• Extension points to prefer: custom connectors, job middleware, and event listeners. Avoid monkey-patching package classes or extending internals — those are exactly what a 1.6.0 can refactor without a major version bump.
• Pin with a caret (^1.6) and commit the lockfile. Since the changelog for this release is link-only, let CI's integration suite be the thing that tells you a minor bump broke something, not production traffic.