Queue Laravel Package

Getting Started

• Install with composer require pekkis/queue and immediately open vendor/pekkis/queue/ — the repository is not publicly indexed, so the source tree (not the README) is your source of truth for the actual interface names, backend implementations, and constructor signatures.
• Identify the two or three things you actually need: the queue interface (producer side: enqueue/push), the worker/consumer interface (reserve/ack/reject loop), and the factory or backend adapters (Redis, AMQP, in-memory, etc.). Most "queue abstraction" packages of this vintage follow that shape.
• Do not try to wire it into Laravel's dispatch() helper first. This is a standalone abstraction, not a Laravel queue driver. The fastest first use case is a single non-Laravel-shaped workload: a CLI command or an artisan command that pushes a serialized job payload onto a backend and a long-running worker command that pops and processes it, all behind the package's interface.
• Write a five-line smoke test before anything else: instantiate the backend, push one payload, pop it, assert round-trip. If serialization or connection config is going to bite you, it will bite you here rather than in production.

Implementation Patterns

• Bind behind an interface in a service provider. Register the package's queue interface in a Laravel service provider and inject it, rather than resolving concrete adapters throughout your code. This is the entire value proposition of the package: your application code should never name a backend. Swapping Redis for AMQP becomes a container binding change.
• Keep the Laravel queue and this queue mentally separate. Use Laravel's native queue (Queue::push, dispatch, Horizon, queue:work) for anything that benefits from Laravel's job lifecycle: retries, failed_jobs, batching, middleware, events. Use pekkis/queue only where you need backend portability or need to consume from a queue that Laravel does not drive. Mixing them in one code path (e.g., dispatching via Laravel but consuming via this package) is where teams get burned — pick one owner per queue.
• Adapter pattern for your own jobs. Define your own thin job contract (e.g., handle(array $payload): void) and let the package handle transport only. The abstraction library should not dictate your domain job signatures; keep serialization explicit and versioned.
• Worker command as a first-class citizen. Wrap the package's consumer loop in an artisan command with --once, --max-jobs, and --sleep flags, plus signal handling via pcntl or Laravel's Signal-style traps. Supervise it with Supervisor or systemd, exactly as you would queue:work. Long-running workers that never exit are the default failure mode of hand-rolled abstractions.
• Test doubles. Implement the package's queue interface with an in-memory array-backed fake for tests, and bind it in TestCase::setUp. This is usually easier than mocking the concrete adapter and gives you assertion helpers ("was a payload pushed?").
• Configuration. Move connection details into config/queue.php under a custom key (e.g., queue.connections.external) and resolve them in your provider. Do not let the package read env vars directly if it offers that — centralize it.

Gotchas and Tips

• This is not a Laravel queue driver. There is no Queue connector, no Job class integration, no failed_jobs table, no retry/backoff semantics for free. If your team assumes dispatch(new MyJob) will route through this package, you will spend a sprint discovering it does not.
• License is NOASSERTION. That is a legal flag, not a cosmetic one — no recognized SPDX license was declared. Get sign-off before shipping it in a commercial product, and check the actual LICENSE/composer.json in vendor/ rather than trusting the Packagist metadata.
• Maintenance and maturity signals are weak. 18 stars and a low health score mean you should expect stale PHP version constraints, missing PHP 8.2+ type declarations, and no security responsiveness. Check composer.json require for the PHP and extension constraints before adopting; a package like this often pins php: ^7.x and needs a fork.
• Serialization is your problem. Abstraction layers typically pass through raw strings or arrays. Decide on JSON (human-debuggable, version-tolerant) over PHP serialize() (class-name coupling, unsafe on untrusted input), and stamp a schema version into every payload so you can evolve job shapes without draining the queue.
• Visibility timeout / ack semantics differ per backend. Redis lists, AMQP, and SQS-style backends have wildly different at-least-once guarantees. Read the specific adapter's code, not the interface docblock, and make every consumer idempotent. Assume duplicate delivery.
• Debugging path: start at the adapter implementation. If a job vanishes, the bug is almost always in the ack/reserve/reject dance or a swallowed exception inside the worker loop, not in your application code. Add structured logging around reserve → process → ack in your worker command.
• Extension point worth using: if you only need one backend, skip the package's abstraction entirely and write a 60-line adapter against your own interface. A 18-star, low-health dependency is hard to justify when the abstraction surface you need is small — adopt it only if it genuinely saves you multi-backend work.