Supervisor Laravel Package

Technical Evaluation

Baseline: No prior assessment exists, so this establishes one. The evaluation below is drawn from the 3.1.0 release note only; the package internals (config schema, console commands, test coverage) were not available for review and are flagged as open questions rather than assumed.

Architecture fit. The package is a deployment-time code generator: it turns application configuration into supervisord program stanzas. It has no runtime coupling to the Laravel request path, no database surface, and no middleware. The 3.1.0 feature — an optional group key emitting a [group:<name>] section — is a config-generation concern that mirrors a first-class supervisor primitive. That is the right layer for it: it does not invent an abstraction, it exposes one the daemon already models. Blast radius of the change is limited to generated artifacts and the deploy scripts that consume them.

Integration feasibility. Low effort. The change is additive in both directions the note calls out: group defaults to an empty string, so unconfigured output is byte-for-byte identical to 3.0.0; and $group is appended as the last constructor argument of SupervisorConfigGenerator with a default, which is source-compatible for positional callers and for container autowiring. Adoption is a config edit plus a deploy-script edit, not a refactor.

Technical risk. Four items are worth gating on:

1. Supervisor version floor. Group-scoped supervisorctl update <group> requires supervisor 3.2+. Hosts below that either reject the argument or silently mismatch behavior — the note does not say which. This must be verified before any deploy script is changed, because a half-applied deploy can leave workers stopped.
2. Process renaming on existing deployments. Adding group to a project already running ungrouped renames its programs, and a group-scoped update will not remove the old ungrouped ones. If both sets are left running, workers double up — duplicate queue consumption, duplicated scheduled jobs, doubled memory. This is the highest-severity failure mode in the release.
3. Version skew between generator and daemon. The package can emit a group section regardless of what the host daemon supports; nothing in the note suggests a guard.
4. Constructor extension. Appending an optional final parameter is BC-safe for callers, but any in-house subclass of SupervisorConfigGenerator that overrides the constructor will break its parent call signature.

Key questions.

• Does the generator read group from Laravel config (config file / env), and is the name validated or escaped? Group names flow into supervisorctl invocations and an INI section header, so quoting matters.
• Is [group:x] emitted before or after the program stanzas, and is the programs = ... list derived from all generated programs or a declared subset?
• Does the package ship artisan commands that wrap reread/update/restart, or do teams hand-roll those in deploy scripts? The answer determines how much of the migration we own.
• What is the failure behavior on supervisor <3.2 — error, warning, or silent no-op?
• Is the one-off migration (stop ungrouped, reread, update, start grouped) documented as runnable steps, and can it be scripted idempotently?
• Can a project declare more than one group, and can a group be removed cleanly later?
• What is the maintainer/bus factor and test coverage on this repo? (Single-author package; worth a note in the risk register.)

Integration Approach

Stack fit. Good fit for the common Laravel deployment shape: one VPS or VM running a single supervisord that hosts several applications, each with queue workers, Horizon, scheduler workers, or a websocket process. Today those projects contend for the same control surface; a per-project group is the natural boundary. Projects with a dedicated supervisord instance per app gain little — the group buys them naming symmetry, not isolation.

Migration path. Treat it as two independent changes so each can be reverted alone:

1. Bump to 3.1.0 with no config change. Regenerate configs and diff against the current output; expect zero bytes of difference. This validates the byte-for-byte claim on your own config before you rely on it.
2. In a later, separately scheduled change, set group. Run the documented one-off migration (stop the ungrouped programs, reread, update <group>, start <group>:*), then confirm no ungrouped programs remain via supervisorctl status. Do not combine the bump with the group adoption in a single deploy — if the diff is not clean in step 1, you want to know that before the process names move.

Compatibility. PHP and Laravel version support appear unchanged by this release. The hard external dependency is supervisor 3.2+ on every host, which is an infrastructure prerequisite, not a package one. Also worth confirming: the release note's example uses Symfony-style %kernel.project_dir% syntax and app:worker commands. If this is a Laravel-targeted package, verify the example is illustrative rather than indicative of a Symfony-first codebase with Laravel as a secondary path.

Sequencing. (1) Inventory supervisor versions across all hosts. (2) Bump and diff. (3) Choose a namespaced group name per project (<project> or <org>-<project>) to avoid collisions on shared hosts. (4) Trial in staging including the one-off migration. (5) Update deploy scripts and runbooks — replace stop all/reload with group-scoped stop <group>:*, reread, update <group>, start <group>:*. (6) Migrate production during a low-traffic window. (7) Remove reload from scripts entirely, since it restarts the daemon and every project on the machine.

Operational Impact

Maintenance. One new optional config key; the test matrix gains a with-group/without-group axis. The main ongoing cost is the raised supervisor floor — hosts must stay at 3.2+, which becomes a documented infrastructure constraint that someone has to own. Pin the package version and watch for changes to the constructor signature or the group-section emission order.

Support. Runbooks and on-call docs must change: myapp:worker addressing, update <group> semantics, and the distinction between update (picks up config changes) and reload (restarts the daemon and everything on the box). Support staff who previously knew stop all need the new incantations, and need to recognize the symptom of orphaned ungrouped workers.

Scaling. The feature improves horizontal tenancy, not throughput: it lets more projects share one supervisord without deploys stomping each other's queues. It does not remove the single-daemon single-point-of-failure, and it does not raise the per-machine process ceiling. If the goal is deploy isolation at higher density, this is a genuine step; if the goal is capacity, it isn't.

Failure modes.

• Duplicate workers after adopting group without completing the ungrouped cleanup — duplicate job execution and doubled resource use. Highest likelihood, highest impact.
• Deploy aborts mid-sequence on a host below supervisor 3.2, leaving workers down.
• Group name typo — control commands target a non-existent group and either error or do nothing, which reads as "deploy succeeded" in a script that does not check exit codes.
• Forgotten configuration — the empty-string default means an omitted group silently preserves the old machine-wide behavior with no warning.
• Partial config pickup — group-scoped update adds and changes programs but is not a general cleanup mechanism for programs removed from config.

Ramp-up. Developers: low — one config key, one deploy-script line. Ops/SRE: moderate — new deploy choreography, a one-time migration procedure, and a version prerequisite to verify fleet-wide. Budget a short pairing session between whoever owns deploys and whoever owns the hosts before the first production adoption, and rehearse the one-off migration in staging first.