Rabbitmq Supervisor Bundle Laravel Package

Getting Started

This is not a Laravel package — phobetor/rabbitmq-supervisor-bundle is a Symfony bundle that generates a supervisord.conf and wraps supervisorctl so you can run N rabbitmq:consumer workers without hand-writing supervisor configs. There is no service provider, no config/*.php publishable, and no kernel.project_dir in a Laravel app. So "getting started" means deciding which half of it you actually want.

Look here first:

1. Resources/config/ — the service definitions and the supervisord config template. This is the real deliverable; the PHP is thin.
2. Command/ — the rabbitmq:supervisor:start / :stop / :restart commands and the options they accept.
3. The generated supervisord.conf in your pid_dir/log_dir after a first run — read it, because that file is what you'll be copying for Laravel.

Minimal steps (Symfony worker app, if you have one):

composer require phobetor/rabbitmq-supervisor-bundle
# register the bundle in AppKernel / bundles.php
app/console rabbitmq:supervisor:start --processes=4
app/console rabbitmq:supervisor:status
app/console rabbitmq:supervisor:stop

Minimal steps (Laravel app, the common case): don't install it. Run the bundle once in a throwaway Symfony skeleton (or read the template in the repo) and lift the generated [program:...] blocks into your own supervisord.conf. That gets you the same numprocs + process_name + signal-group behaviour with zero Symfony coupling.

First real use case: replacing a hand-maintained [program:worker] stanza that only ever runs one queue worker, with an N-worker group you can stop and restart as a unit on deploy.

Implementation Patterns

Pattern A — Symfony app owns the workers, Laravel owns the web tier. If your org already runs a Symfony console app for consumers, let this bundle manage them and have Laravel publish into the same broker. Nothing crosses over except the queue/exchange names. This is the lowest-friction path and the one the package is actually designed for.

Pattern B — steal the config, keep Laravel. Port the generated supervisor blocks. The shape it produces, and what you should reproduce, is roughly:

[program:consumer]
command=php /app/artisan rabbitmq:consume %(process_num)s
process_name=%(program_name)s_%(process_num)02d
numprocs=8
stopasgroup=true
killasgroup=true
autorestart=true
stopwaitsecs=30

The stopasgroup/killasgroup pair is the important part: it's the plain-supervisord equivalent of 3.3.0's "group consumers" change, and without it supervisorctl stop only signals the wrapper shell while the PHP child keeps draining.

Deploy workflow with 3.3.0 semantics. Because supervisord is now waited for by default, your deploy script can collapse:

# before: start, then poll for the socket
./bin/console rabbitmq:supervisor:start --processes=8
until [ -S /var/run/supervisor.sock ]; do sleep 0.5; done

# after: start returns when supervisord is actually up
./bin/console rabbitmq:supervisor:start --processes=8

This matters most in CI and in docker-compose healthchecks, where the previous behaviour produced flaky "supervisor not running" races right after container start.

Restart-on-deploy ordering. stop (wait for in-flight messages, stopwaitsecs) → git pull / composer install → start. Do not restart; with parallel group signalling, a restart fans out the stop to every worker at once and you get a burst of reconnections and PRECONDITION_FAILED churn on the broker.

Healthcheck integration.

./bin/console rabbitmq:supervisor:status || exit 1
# inspect worker count
supervisorctl status 'consumer:*' | grep -c RUNNING

Prefix-based group status is the natural companion to the new grouping — it lets you ask "are all 8 consumers up" in one call instead of iterating program names.

Extension points worth knowing. The supervisor service is a normal container service, so you can decorate it in Symfony to add metrics. In Laravel terms the equivalent is wrapping supervisorctl in a small artisan supervisor:status command of your own that shells out and reports to your monitoring.

Gotchas and Tips

The Symfony 3+ path change is a silent relocation. kernel.project_dir resolves to the project root; kernel.root_dir/.. resolves to the parent of app/. If your project root is app/'s parent, nothing moves — fine. If your layout differs, your log_dir, pid_dir, and the generated supervisord.conf will appear somewhere new after upgrading, and the symptom is "supervisorctl can't find the socket" rather than a clear error. Diff the generated config path before and after the upgrade.

"Wait for supervisord by default" can turn a fast failure into a hang. Previously a broken supervisord binary or unwritable pid dir made start exit and your deploy fail loudly. Now start blocks waiting for a socket that will never appear. If the command exposes a no-wait flag, use it in contexts where you want to surface the spawn error; otherwise wrap the call in timeout 60 in CI and check supervisord.log for the real cause (almost always a bad executable path or a missing user=).

Grouping is a behavioural change shipping in a minor version. Program names and the target you pass to supervisorctl may differ from 3.2.x. Anything that scripts supervisorctl stop consumer_myqueue_00 or parses status output per-process is at risk. Grep your deploy scripts, cron jobs, and monitoring configs for consumer_ before rolling this out.

Parallel signals amplify load. Sending the stop signal to the whole group simultaneously means N workers all finish their current message and close their AMQP connection within the same second, then all reconnect together on start. With 16+ workers against a small broker this shows up as connection-refused noise or DB connection-pool exhaustion in the consumer code. Stagger if it hurts — that's the tradeoff you're making against 3.2.x's sequential signalling.

Log rotation is your problem, not the bundle's. Each program gets its own child log under log_dir. Defaults for logfile_maxbytes/logfile_backups are modest and the consumers' stdout (var_dump in a forgotten debug branch) fills them fast. Set them explicitly and make sure the user running supervisord can write to log_dir — permission failures there produce a supervisord that starts and then dies with a confusingly empty log.

Never run supervisord as root without user=. It warns but proceeds, and every consumer process inherits root — including anything it writes to disk or to the queue.

Debugging ladder: supervisorctl status → supervisord.log (spawn/exec errors) → per-program child log (application errors) → the generated config file (wrong command or path). The failure is almost never in the bundle's PHP; it's in the config the bundle emitted.

Don't install this into a Laravel app to "see if it works." Symfony bundles require the DI container and kernel bootstrapping; you'll spend more time stubbing KernelInterface than writing the six-line supervisor stanza you actually needed. Laravel's own answer here is Horizon (for Redis) or plain supervisord — the value this bundle offers you is the config template and the group-signal pattern, not the code.