Laravel Essentials Kit Laravel Package

Technical Evaluation

Architecture fit This release extends the package from "PHP dependency scaffolding" into "deployment topology ownership." Prior opt-ins (SATIM, captcha) touched composer.json and a config file; Reverb touches .env, .env.example, generated frontend assets, the production Docker Compose stack, and both nginx layers. That is a materially larger blast radius and shifts the package's contract from library installer to infrastructure generator. The design itself is coherent: Reverb is a first-party Laravel package, and the installer delegates to official artisan commands (install:broadcasting --reverb --without-node, reverb:install) rather than reimplementing setup. The --without-node flag plus the removal of resources/js/echo.js when no package.json exists is a sensible guard that keeps API-first / PHP-only projects from accumulating dead frontend artifacts.

Integration feasibility High. The opt-in mechanism mirrors the existing SATIM/captcha pattern (interactive yes/no plus a --packages=reverb non-interactive path), so it slots into the package's established UX and into CI/automation flows without a new paradigm. The Docker additions are additive and gated: stacks without Reverb are explicitly unchanged, which keeps the upgrade path for existing users non-breaking for a minor version (v1.3.0). The architectural choice to proxy /app/ (WebSocket) and /apps/ (signed HTTP API) at both nginx layers, with upgrade headers, means clients and external publishers use the app's own origin — that avoids CORS configuration and a second TLS certificate, at the cost of coupling real-time availability to the web tier's routing table.

Technical risk

• Env mutation is the sharpest edge. Writing BROADCAST_CONNECTION=reverb and declaring REVERB_* keys requires idempotency. Re-running the installer on an existing Reverb project, or on a project where BROADCAST_CONNECTION was deliberately set to log/sqs/redis, is the most likely source of silent breakage. Needs confirmation whether existing values are detected and preserved or overwritten.
• Undocumented capacity regression. Reverb's 256 MB is carved out of the queue container's default, which drops to 512 MB. This is a real reduction in headroom for job-heavy applications and is not something a user opting into "add WebSockets" would expect to trade away. It needs to be surfaced in output and ideally made configurable.
• Single-instance real-time. One reverb container with resource caps is a single point of failure for WebSocket connectivity and has no documented horizontal-scaling story (which for Reverb implies a shared pub/sub layer, typically Redis). Fine for small/medium deployments; a ceiling for anyone scaling.
• Path-based routing collisions. Claiming /app/ and /apps/ on the application origin is a naming decision that can conflict with existing routes. Low probability, high annoyance when it hits.
• Delegation fragility. Depending on install:broadcasting flags means a future Laravel release renaming or removing --without-node breaks the installer. Acceptable, but warrants a version constraint and a test.

Key questions

1. Is .env mutation idempotent, and does it preserve a user-set BROADCAST_CONNECTION?
2. Are REVERB_* keys in .env.example emitted with empty placeholders or generated secrets — and is there a clear signal that production values must be set?
3. Is the queue memory reduction (768 → 512 MB) configurable, and is it announced during install?
4. Is there an uninstall/disable path (--packages= without reverb, or a removal command), and does it clean up compose and nginx changes?
5. What is the supported path to more than one Reverb container, and is that explicitly out of scope?
6. Are wss:// termination and any upstream load balancer / CDN WebSocket support documented, or assumed?

Integration Approach

Stack fit Targets Laravel 11/12-style broadcasting with the first-party Reverb server. The --without-node posture makes this a strong fit for API-first, Blade/Livewire, and PHP-centric teams that have no Vite build in production — precisely the audience most underserved by the standard Echo/Node-centric Reverb docs. It composes cleanly with the package's existing Docker production generator (nginx + app + queue), reusing the same image for the new service rather than introducing a second build artifact.

Migration path Two distinct cohorts. New projects get a coherent end-to-end setup from the installer — the lowest-friction path and the one to validate first. Existing projects are riskier: the Docker changes only materialize on a re-run of the generator, so teams with hand-edited compose files must diff the regenerated output rather than accept it. Recommend documenting "regenerate to a temp directory and diff" as the standard procedure. Non-Reverb users require zero action — the explicit "stacks without Reverb are unchanged" guarantee is the most important sentence in these notes and should be preserved as a hard compatibility contract in future releases.

Compatibility

• Requires the Reverb package and a working broadcasting auth flow; private/presence channels need the app's auth guard to be reachable from the WebSocket origin.
• Production deployments must set real REVERB_APP_KEY / SECRET / APP_ID and a host reachable from both the browser and any external publisher — the .env.example declarations define shape, not values.
• Any reverse proxy, load balancer, or CDN above the shipped nginx must also pass Upgrade/Connection headers and not buffer or time out idle WebSocket connections. This is outside the package's control and is the most common real-world failure point.
• Removal of resources/js/echo.js is safe only when there is genuinely no package.json; confirm the check is on file presence, not on a heuristic.

Sequencing

1. Enable via prompt or --packages=reverb; verify artisan commands complete and capture their output.
2. Review .env / .env.example diff — confirm no clobbered values and that secrets are placeholder-only.
3. Regenerate the Docker stack and diff against the committed compose file before merging.
4. Confirm nginx /app/ and /apps/ locations and upgrade headers in both layers; check for route collisions.
5. Configure clients manually where echo.js was removed (Echo or raw Pusher-protocol client) and verify connection over wss://.
6. Validate external publisher path against /apps/ on the app origin.
7. Load and soak test: confirm queue containers survive at 512 MB under realistic job volume, and that Reverb healthcheck restarts behave as intended.
8. Extend to staging/upstream LB configuration before production cutover.

Operational Impact

Maintenance The package now owns a stateful service definition plus two nginx proxy blocks, so its maintenance surface grows: Reverb's healthcheck path (/up), upgrade-header conventions, and memory defaults must be tracked against upstream Laravel releases. The reliance on install:broadcasting flags should be pinned and covered by an automated smoke test on each Laravel minor. Versioning discipline matters — keep Reverb as opt-in and keep the "no Reverb = no change" guarantee, so the majority of users are unaffected by this maintenance burden.

Support Expect a new and distinctly non-PHP ticket class: "WebSockets won't connect." The realistic top five are (a) ws:// vs wss:// mixed content behind TLS, (b) upstream proxy stripping upgrade headers or buffering, (c) 502 on /app/ because the Reverb container is unhealthy or not on the network, (d) private-channel auth failing due to guard/session/CSRF mismatch, and (e) external publishers hitting /apps/ with a wrong or unsigned request. Each of these needs a documented diagnostic. Without it, support load will land on the package maintainers rather than on the app team.

Scaling Vertical only in the shipped configuration: one capped container at 256 MB, with no pub/sub layer to coordinate multiple instances. That is appropriate for small-to-medium apps and for Livewire-style single-server deployments, and it should be documented as such rather than left implicit. The queue memory reduction is the more consequential scaling note — 512 MB is a meaningful reduction for apps that run image processing, exports, or fan-out jobs, and it will manifest as opaque OOM kills weeks after the WebSocket feature was added. Make it a configurable knob and echo the chosen values at install time.

Failure modes

• Reverb down: nginx returns 502 on /app/ and /apps/; HTTP traffic to the app is unaffected. Good isolation — real-time degrades rather than the site going down. The /up healthcheck should trigger container restart under a proper orchestrator.
• Queue OOM after the memory carve-out: silent, delayed, hard to attribute to this change. Highest-severity operational risk in the release.
• Env drift on re-install: duplicated or overwritten REVERB_* entries, causing auth failures that look like client bugs.
• Path collision on /app/ or /apps/: app routes become unreachable behind the proxy.
• Idle-connection timeouts or buffering at an upstream LB: intermittent disconnects that reproduce only in production.

Ramp-up Low for PHP developers — the entire appeal of --without-node is that no JS toolchain is required, and the artisan commands do the configuration work. Moderate for operators and platform engineers, who inherit a new container, a new proxy contract, TLS for wss://, and an amended memory budget. Budget most of the enablement effort on the ops side and on one canonical "adding Reverb to an existing project" runbook; treat the installer's own output as the first draft of that documentation.