Laravel Essentials Kit Laravel Package

Getting Started

This package is a project scaffolder: it asks which optional integrations you want (SATIM payments, captcha, and as of v1.3.0 Reverb), then materializes the code, env keys, and production Docker/nginx layers for each. The fastest way to understand it is to run it once on a throwaway project and diff the result.

1. Require the package as a dev dependency and run the installer:

   composer require --dev <vendor>/<package>
   php artisan <package>:install
   

2. Answer the prompts. Each integration is a yes/no question; you can skip the interactivity entirely:

   php artisan <package>:install --packages=satim,captcha,reverb
   

3. Look first at:
   • The command class and its --packages parsing (this is the registry of supported integrations).
   • The stubs directory — docker-compose*.yml, nginx/*.conf, .env.example fragments. Everything the release notes describe lives here.
   • Any generated docker/ (or similarly named) directory in your app after the run.

First use case — adding Reverb to an existing app: run the installer with --packages=reverb against a project that already has your Docker setup, then diff. You should see install:broadcasting --reverb --without-node and reverb:install invoked, BROADCAST_CONNECTION=reverb in both .env and .env.example, the REVERB_* keys declared in .env.example, and — if you have a package.json — a generated resources/js/echo.js you can wire your frontend to.

Implementation Patterns

Treat the installer as a one-shot generator, not a runtime dependency. Run it at project bootstrap (or when deliberately adding an integration), commit the output, and review the diff like any other code change. Don't re-run it casually on a live project.

Non-interactive is the norm for CI and for re-provisioning. The yes/no prompts map cleanly onto --packages=. In a scripted setup, pass the full list explicitly rather than relying on prompt defaults, so adding a new integration upstream doesn't silently change your scaffold.

Local vs. production are two separate passes. Reverb setup itself is local-first: install:broadcasting --reverb --without-node + reverb:install gives you a working reverb:start and Echo client. The Docker work is the production pass: a dedicated reverb service built from the same image, its own entrypoint, a healthcheck against Reverb's /up, and resource caps. Plan to review both artifacts independently.

Routing model to internalize. In the generated stack:

• nginx proxies /app/ (WebSocket) and /apps/ (Reverb's signed HTTP API) to the reverb service with upgrade headers.
• Internal publishers (app and queue containers) talk to reverb:8080 over the Docker network — no nginx hop, no TLS.
• External publishers and browser clients hit your API's own origin and get proxied through.

So your Echo config and any server-side broadcasting config point at different things depending on where the code runs. Keep the internal host (reverb:8080) in container env and the public host in the browser bundle.

Budget memory deliberately. Reverb takes 256 MB out of the queue service's default, leaving queue at 512 MB. If your queue workers handle heavy jobs (media processing, large exports), raise the queue cap in the generated compose file rather than accepting the new default.

Extend via the package registry and stubs, not by editing generated files. If you need a fourth integration, follow the Reverb pattern: a prompt/--packages key, a stub set, env-key declarations in .env.example, and a conditional branch in the Docker/nginx generation. Editing the emitted docker-compose.yml directly means the next re-run loses your changes.

Pin the image across services. The Reverb container runs from the same image as app/queue. Keep them on one build so reverb:start and your app code never drift.

Gotchas and Tips

• echo.js is deleted when there's no package.json. That's correct behavior (nothing to build it), but if you add Vite/npm later, the file won't come back on its own. Re-run the Reverb setup or recreate it manually.
• BROADCAST_CONNECTION is overwritten. If you already broadcast over Pusher/Redis, adding Reverb will flip it. Diff .env and .env.example after the run, and check config/broadcasting.php connections are still intact.
• .env.example gets the REVERB_* keys; .env gets the connection switch. The real credential values are produced by reverb:install into .env. Copy them into your secret store for deployed environments — don't ship .env.example values.
• reverb:start binds to localhost by default inside a container. If WebSocket connections fail with a 502 from nginx, confirm the entrypoint passes a --host=0.0.0.0 (and the right --port). This is the most common post-generation fix.
• The healthcheck relies on Reverb's /up. If the container is "healthy" but sockets fail, the problem is the nginx upgrade headers or a path mismatch on /app/, not the process.
• Don't publish reverb:8080 to the host. It's an internal hop. External traffic should enter through nginx on /app/ and /apps/; that's what makes "the API's own origin" work for clients and third-party publishers.
• Stack ordering matters for /apps/. Reverb's signed HTTP API requires valid app credentials. External publishers need the app key/secret and the public origin — not the container hostname.
• Reverb is single-instance as generated. There's no Redis-backed horizontal scaling in this scaffold. If you need more than one Reverb container, you're outside what the package gives you.
• Stacks without Reverb are untouched — the generation is conditional. If a re-run suddenly changes your compose file, check whether reverb accidentally ended up in your --packages list or a prompt default.
• Debugging order: docker compose ps (health) → nginx logs for /app/ upgrade errors → reverb:start container logs → BROADCAST_CONNECTION value in the running app container → Echo's host config in the browser. That sequence isolates env vs. proxy vs. process problems quickly.
• Watch the queue memory drop (768 MB → 512 MB in a default-generated stack). Silent OOM kills in queue workers after this release are almost always this.