Chattle Laravel Package

Getting Started

This release is a compatibility pin, not a feature release. Before anything else, check your composer.json — v2.0.0 constrains Laravel to ^10.0 because it depends on beyondcode/laravel-websockets, which is archived and cannot install on Laravel 11+. If you are on Laravel 11 or 12, composer require will fail or force a framework downgrade; stop there and evaluate alternatives (see Gotchas).

If you are on Laravel 10:

1. composer require <vendor>/<package>:^2.0 and confirm the lockfile did not try to move laravel/framework.
2. Read the package's composer.json first — the Laravel constraint and the beyondcode/laravel-websockets constraint are the two things that will bite you.
3. Publish config and migrations: php artisan vendor:publish --provider="..." and inspect config/websockets.php.
4. First use case: run php artisan websockets:serve locally with BROADCAST_DRIVER=pusher pointed at 127.0.0.1:6001, and confirm a broadcast(new MyEvent(...)) reaches the browser via Laravel Echo.

Treat the published config file as the real documentation entry point — the archived upstream means there is no maintained doc site to lean on.

Implementation Patterns

Standard broadcast wiring. Point config/broadcasting.php's pusher connection at your websocket host, keep the app key/secret in .env, and let the package bridge the server process. This is the dominant pattern and should be your default.

Channel authorization. Register private and presence channels in routes/channels.php as usual — the package resolves them through the same Broadcast::channel callbacks. Keep authorization logic in that file rather than in event constructors so it stays testable.

Supervised long-running process. In production, run the server under Supervisor or a systemd unit, not artisan serve. Set max_request (or equivalent restart interval) in config to bound memory growth, and let the supervisor restart it.

Reverse-proxy TLS termination. Run the websocket server on plain HTTP behind Nginx/Caddy and terminate TLS at the proxy. Do not try to make the PHP process handle certificates — this is the pattern the upstream expects.

Horizontal scaling. For more than one app server, enable the Redis-backed scaling options in the config and share the same Redis instance across app and websocket processes. Single-node setups should leave this off; it adds failure modes for no benefit.

Dashboard access control. If you expose the /laravel-websockets dashboard, gate it behind middleware — the published config has an authorization callback, and leaving it default in production exposes connection stats and the ability to send test events.

Frontend integration. Use laravel-echo + pusher-js on the client; nothing about the client changes versus hosted Pusher. Keep the Echo instance in a single module and reuse it, rather than instantiating per component.

Gotchas and Tips

• The version pin is the headline risk. v2.0.0 hard-caps Laravel at 10. That means this package's upgrade path is now tied to an archived dependency that receives no security fixes. Plan an exit: Laravel Reverb is the first-party replacement and is where most teams should be migrating for Laravel 11+.
• composer update can silently downgrade the framework. If the constraint is loose elsewhere in your tree, Composer may resolve to Laravel 10 to satisfy this package. Run composer why-not laravel/framework 11.* when resolution gets weird.
• Archived upstream means no upstream bugfixes. Anything you hit in beyondcode/laravel-websockets is yours to patch. Prefer configuring around issues rather than forking.
• Config is cached. After touching config/websockets.php, run php artisan config:clear; a stale cached config is the most common "my change did nothing" cause.
• Connection failures are usually proxy or scheme mismatch. If Echo connects but immediately drops, check wss:// vs ws:// and whether your proxy forwards the Upgrade and Connection headers.
• Events dispatched inside transactions may arrive before commit. Use broadcast(...)->afterCommit() or ShouldDispatchAfterCommit to avoid clients reacting to rows that later roll back.
• Debugging: tail the websockets:serve process output with verbose flags before assuming an app-side bug; most "events not arriving" reports are queue workers not running, not the websocket server.
• Extension points are thin. The practical hooks are the config file, the channel authorization callbacks, and the dashboard middleware — do not build deep customizations on top of an archived package.