Multi Process Queue Laravel Package

Getting Started

Requirements to verify before anything else: the Swoole PHP extension (php --ri swoole), a supported PHP version, and a reachable Redis connection if the package uses Redis as its backing store. Because the package relies on Swoole's process and coroutine primitives, it will not run on typical shared hosting where proc_open is disabled or Swoole can't be installed — plan for a VPS/container where you control the PHP build.

Steps:

1. composer require yuntian001/multi-process-queue and pin the resolved version in composer.json (last tag is from January 2023, so pin exactly rather than floating).
2. Confirm the service provider was auto-discovered; if not, register it in config/app.php.
3. Publish the package config (php artisan vendor:publish --provider="Yuntian001\MultiProcessQueue\...") — verify the exact provider namespace from the README, it's the fastest way to see worker count, timeout, retry, and broker settings in one place.
4. Define a job class with the package's expected entry point (convention is a public handle() method that receives the payload). Keep the constructor small — it's what gets serialized.
5. Dispatch the job from a controller or route and start the worker with the package's artisan command (it follows the queue:work style; confirm the exact signature in the README before scripting it into Supervisor).
6. First meaningful use case: move an email send or an external API sync out of the request/response cycle. Measure the p95 request time before and after — that's the fastest way to confirm the millisecond-level latency claim applies to your workload.

Where to look first: the published config file (it tells you the real defaults faster than the README), then the package's console command class, then the README's minimal example. With 93 stars the documentation is likely terse, so read the source for anything ambiguous.

Implementation Patterns

Producer side. Dispatch from controllers, model observers, and scheduled commands the same way you'd dispatch a Laravel job — but keep payloads scalar and small. Serialize an ID or a small DTO, not an Eloquent model, so retries don't rehydrate stale state.

Job design. Treat each job as idempotent. Because timeout control and retry are built in, a job can be re-executed after a partial success; use a dedupe key or a status column so repeated runs are safe. Put retry/timeout tuning as job-level properties (or per-job config entries) rather than editing global worker config for a single slow job.

Worker topology. Size worker_num to your measured job latency and target throughput, not to the machine's core count. Enable coroutine mode for IO-bound jobs (HTTP, Redis, DB) so a single worker can multiplex; keep CPU-bound jobs in a separate worker pool or accept that they will block the event loop.

Framework integration. The package is designed to coexist with Laravel's native queue. A pragmatic migration pattern is: new work goes onto multi-process-queue, existing work stays on the database/Redis driver, and you retire the native queue once failure handling and monitoring have proven themselves. Register a Supervisor program (or systemd unit) so the worker restarts automatically; wire SIGTERM/reload into your deploy script so workers pick up new code.

Observability. Add structured logging inside handle() with a job ID in the context, and surface failures to the same channel your Laravel queue uses. Without this, a 93-star package with a sparse UI leaves you debugging from ps and log tails.

Testing. Don't spin up a real worker in tests. Call handle() directly with a fixture payload, or expose a synchronous dispatch path behind an interface so tests and local dev don't require Swoole.

Gotchas and Tips

• Long-running process = stale code. Swoole workers cache the autoloader and the Laravel container. Restart workers on every deploy; in development, run with a file watcher. A missing restart is the single most common source of "my fix doesn't work" confusion with this class of package.
• State pollution. Laravel singletons, static caches, and facade roots persist across jobs in the same worker. Reset scoped bindings per job or avoid statics inside job classes. Memory grows if job payloads accumulate in long-lived objects — watch RSS over a few thousand jobs.
• Blocking IO. Coroutine hooks only cover certain functions; a blocking PDO or a file_get_contents call will stall the whole worker. Use coroutine-safe Redis/MySQL clients where available, and benchmark under concurrency rather than trusting the "supports coroutines" line.
• Timeout semantics. Verify whether the timeout config is seconds or milliseconds before setting it — the README advertises "millisecond-level" latency, which makes unit confusion easy. A timeout that fires mid-job is another reason to insist on idempotency.
• Retry storms. Default retries with no backoff will hammer a downstream service during an outage. Combine a capped attempt count with an explicit dead-letter/failed store you actually inspect.
• Redis collisions. If you share Redis with Laravel's native queue, use distinct databases and key prefixes. Verify the connection name the package reads — it won't necessarily honor QUEUE_CONNECTION.
• Config cache. php artisan config:cache is easy to forget after changing worker_num or timeout; the running worker won't see edits until you rebuild and restart.
• Maintenance risk. The last release is January 2023. Test on your target PHP 8.2+/Swoole 5/Laravel 11 stack before committing. If there are incompatibilities, the codebase is small enough to fork — budget an afternoon for a compatibility patch rather than betting on an upstream release.
• Graceful shutdown. Make sure the worker drains in-flight jobs on SIGTERM; a hard kill during a retry-heavy job leaves ambiguous state in whatever the job was mutating.