Jobqueue Laravel Package

Getting Started

Because this is a low-profile package (16 stars, last release Dec 2022), treat the repo README and composer.json as the source of truth before wiring anything into a real app. Confirm the Laravel/PHP version constraints first — a package frozen at the end of 2022 will typically target Laravel 8–9 and may need illuminate/* constraints bumped (or a fork) to run on Laravel 10/11.

Minimal path:

1. composer require sfcod/jobqueue
2. Publish the config/service provider assets: php artisan vendor:publish --provider="Sfcod\Jobqueue\JobqueueServiceProvider" (check the actual provider FQCN in the repo — provider naming is the most common trip-up here)
3. If the package ships its own job/tracking tables, run php artisan migrate and inspect the migration for table names before letting it near an existing schema.
4. Register the connection/config in config/queue.php (or wherever the README points) and clear config: php artisan config:clear.
5. First use case: dispatch one trivial job through the package's API (a logged "hello world") and process it with a worker, so you validate the full dispatch → store → worker → completion loop before building on it.

Where to look first: the README's quickstart, then src/ for the service provider (which reveals config keys, bindings, and any custom queue connection), then the config/ and database/migrations/ folders shipped with the package.

Implementation Patterns

• Wrap, don't couple. Expose the package behind your own small service or a thin trait so the rest of the app calls YourDispatcher::push($job) rather than package classes directly. Given the maintenance risk, an isolation seam makes a later swap to Laravel's native queue a small change instead of a refactor.
• Connection-swap pattern. If the package provides a queue connection/driver, register it alongside sync, database, and redis in config/queue.php and select it per-environment (e.g. jobqueue locally, redis in prod). This keeps rollback to native queues a config change.
• Job class conventions. Keep jobs as plain Laravel ShouldQueue classes where possible; if the package needs its own base class or interface, subclass it and put shared behaviour (retry policy, backoff, tries, timeout) in your base rather than scattering attributes.
• Tracking/monitoring integration. If the package stores job state, poll or subscribe to its events to feed your existing observability (Horizon-style dashboards, health checks, Slack alerts on failures). Don't build a second dashboard — hook its events into what you already have.
• Testing. Lean on Queue::fake() / Bus::fake() for assertions and reserve real package round-trips for a single integration test against a throwaway DB. If the package ships a fake or test helper, prefer it; otherwise keep package-specific test setup in one base test case.
• Migration order matters. If it ships tables, schedule its migrations after your core job-related migrations to avoid foreign-key ordering surprises in CI.

Gotchas and Tips

• Maintenance risk is the headline. Last release 2022 and 16 stars means abandoned-or-dormant. Vendor/fork it (repositories with a VCS path or a private fork) if it's load-bearing, so you control Laravel-version bumps and security patches.
• Version compatibility. Verify composer.json constraints for illuminate/* and PHP. Installing on Laravel 10/11 may resolve against stale deps or fail composer update; test in an isolated branch before committing.
• Provider/config discovery. If auto-discovery fails, manually register the provider in config/app.php and re-run config:cache. Stale config cache is the usual cause of "config key not found".
• Migration collisions. Check shipped table names against your schema (e.g. a jobs table clash with Laravel's native queue). Rename via a published migration if needed.
• Worker lifecycle. Package-specific workers may not honour standard signals (queue:restart, SIGTERM) — verify graceful shutdown and timeout handling in staging, especially for long jobs.
• Debugging path. Start with the package's stored job records/state table, then storage/logs/laravel.log, then the dispatch event chain. Add temporary logging around the dispatch call to distinguish "never queued" from "queued but not processed".
• Extension points to look for: custom job model/repository bindings, dispatch/completion/failure events, and middleware hooks — these let you add metrics and retry policy without forking. If none exist, that's a sign to favour a thin wrapper and plan an exit.
• Exit strategy. Document (in a README note) the exact surface you use — connection name, dispatcher method, job base class — so migrating to native Laravel queues or Horizon is a scoped, testable change.