Server Laravel Package

Getting Started

1. Install and publish:

   composer require lrakauskas/tether-server
   php artisan vendor:publish --provider="Lrakauskas\TetherServer\TetherServerServiceProvider"
   php artisan migrate
   

   v1.0.1 cleaned up the README links, so the quickstart is the best place to confirm the exact provider/tag names for your version.

2. Review config/tether.php (or the package’s config file) and set the driver, storage backend, host/port, and auth options in .env.

3. Start the server process in a separate terminal during development—likely an Artisan command such as php artisan tether:serve. In production, run it under Supervisor rather than PHP-FPM.

4. First use case: real-time notifications or a live activity feed. Publish a Laravel event through the package’s broadcaster/API, connect a browser EventSource or WebSocket client to the server endpoint, and confirm the message arrives. Then use the cursor pagination endpoint to fetch missed events on reconnect—v1.0.1 fixes overlapping-timestamp pagination, making catch-up/replay reliable.

Where to look first: README quickstart, config/tether.php, the service provider’s route registration, and any included JS client examples.

Implementation Patterns

• Publishing events: wire Laravel events to Tether via a listener or the package’s broadcast driver. Keep payloads small, versioned, and free of sensitive data.
• Catch-up/replay: treat the event log as append-only. Clients store the last cursor and request events after it on reconnect. Because v1.0.1 fixes overlapping timestamps, ordering by (created_at, id) is safe for replay and initial sync.
• Server lifecycle: run the Tether server as a dedicated long-lived process. Restart it on deploy, and do not run it inside PHP-FPM request workers.
• Authorization: protect private streams with Laravel middleware or the package’s channel authorization callbacks. Test both authorized and unauthorized subscriptions.
• Testing: use Laravel HTTP tests for the feed/cursor endpoints and a fake broadcaster for publish paths. For integration coverage, start the server in CI and assert a published event appears in the stream.
• Scaling: if the package supports Redis pub/sub, use it so multiple server nodes share events. For WebSockets, plan for sticky sessions or a shared backend.

Gotchas and Tips

• Cursor pagination edge case: before v1.0.1, paginating by timestamp alone could skip or duplicate events when multiple records shared the same created_at. Upgrade, and if you write custom queries, always use a unique tiebreaker such as id alongside the timestamp.
• README disclaimer removed: v1.0.1 drops the experimental disclaimer, but that is not a production-readiness guarantee. Pin to ^1.0 and review the changelog before minor upgrades.
• Long-running process quirks: config and code changes require a server restart. Clear php artisan config:cache after .env changes, and watch memory usage with a restart policy.
• Proxy buffering: for SSE, disable Nginx response buffering (proxy_buffering off) and raise timeouts. For WebSockets, ensure upgrade headers are forwarded.
• Debugging: check the server process output first, then Laravel logs. Use browser devtools to inspect the event stream or WebSocket frames, and verify CORS/auth tokens during the handshake.
• Extension points: look for custom event transformers, storage drivers (database/Redis), and authorization callbacks in the config. Since the cursor fix touches the storage/query layer, avoid changing the event table schema without checking package migrations.