Soundboard Laravel Package

Getting Started

Soundboard ships as a Laravel + Livewire application with a first-class Docker image (jncarter/soundboard), so most day-to-day work starts at the container, not the codebase.

1. Read the README and .env.example first. Since v2.6.1, TRUSTED_PROXIES is documented in both — this is the setting you will most often need to touch when running behind a load balancer, reverse proxy, or TLS terminator.
2. Pin an explicit tag in docker-compose.yml. Tags 2.6.1, 2.6, and latest all resolve to this release today, but only the full version tag is reproducible. Use 2.6.1 in production, 2.6 if you want patch-level security updates automatically.
3. Upgrade to v2.6.1 before anything else. It is a security release: pull the new image and recreate containers (docker compose up -d --force-recreate), don't just pull — the old containers keep running the old PHP.
4. First use case: stand the app up, seed roles/permissions, and confirm Livewire interactivity works end to end before wiring in your own domain logic.

If you install from source rather than Docker, confirm php -v reports 8.4.1 or newer (raised from 8.4.0 by the Symfony 8.1 requirement) and that composer.lock resolves symfony/http-foundation to 8.1.9+.

Implementation Patterns

Container upgrade workflow (the common case).

docker compose pull            # fetches jncarter/soundboard:2.6.1
docker compose up -d --force-recreate
docker compose exec app php artisan migrate --force

Run migrate after every upgrade; Laravel minor bumps (13.33 → 13.37 here) occasionally ship schema or config changes that only surface at boot.

Reverse proxy / TLS termination. Set TRUSTED_PROXIES to the proxy CIDR or * only when the app is genuinely unreachable except through the proxy. This is what makes url(), redirects, and Livewire's endpoint generation emit https:// and the correct host. Configure it before you debug "mixed content" or "Livewire update failed" symptoms.

Authorization and auditing. The stack ships spatie/laravel-permission 8.3.2 and spatie/laravel-activitylog 5.1.3, which is a strong hint about intended shape: gate features with permissions rather than ad-hoc role checks, and let the activity log capture mutations. Cache permissions in production (php artisan permission:cache-reset after seeding) and be deliberate about which models are loggable — logging every Livewire property update is a fast way to bloat the table.

Livewire (4.4.7) interaction pattern. Keep state in Livewire components and push side effects into queued jobs or service classes; components should stay thin so this framework bump is a non-event on future upgrades.

Dependency hygiene. Vite, concurrently, and shell-quote are build-time only and do not ship in the image. Treat their Dependabot alerts as CI hygiene, not runtime exposure — but do keep them current so the alerts don't mask a real one.

Gotchas and Tips

• HeaderUtils::split() ReDoS (CVE-2026-108082). Any client could trigger this with a crafted Cache-Control header against symfony/http-foundation 8.0.15. If you consume Soundboard's classes in your own app, or maintain a source install, verify the lock file pins 8.1.9. Docker users get it automatically in 2.6.1 — but only after recreating containers.
• latest is not a version. The 2.6 and latest tags both moved to this release; a silent docker compose pull can jump you across patch versions. Pin the full tag in production and upgrade deliberately.
• PHP minimum moved to 8.4.1. Source installs on 8.4.0 will fail composer install with a platform requirement error. This does not affect Docker users, which is easy to miss if your CI matrix builds from source.
• Trusted proxies are a security boundary, not a convenience flag. Blanket-trusting * lets any client spoof X-Forwarded-For and defeat rate limiting and IP-based logging. Scope it to your actual proxy addresses.
• Migrations can be missed on image-only upgrades. A pull + restart looks successful while the schema lags. Always follow an upgrade with php artisan migrate --force (and config:cache / route:cache if you cache in production).
• Extension points: prefer publishing config and overriding Livewire components or route middleware over patching the image. Nothing in this release changes extension surfaces, so existing customisations should carry over — but re-run your smoke tests after the Symfony minor bump, since header parsing behaviour is exactly what changed.
• Debugging a security bump: if you suspect you're still on the vulnerable build, check the running container rather than the compose file — docker compose exec app php -r 'echo \Symfony\Component\HttpFoundation\HeaderUtils::class;' plus composer show symfony/http-foundation inside the container gives you the real answer.