Laravel Wave

Wave automatically reconnects and resumes event history (default 60s) if a connection is lost. However, to maintain a truly persistent connection and avoid timeouts, you must configure your web server.

Handling fastcgi_read_timeout (Nginx)

By default, Nginx + PHP FastCGI often has a 60s timeout. You can prevent timeouts by:

1. Ensuring frequent events: Ensure events are pushed more frequently than the timeout. Wave can send pings automatically based on the ping.frequency config.
2. Using eager_env: Set ping.eager_env to a specific environment (like local) so pings are sent with every request.
3. Manual Ping Control: Disable automatic pings (ping.enable => false) and use the sse:ping command to send pings at a specific interval.

Handling request_terminate_timeout (PHP-FPM)

Some platforms (like Laravel Forge) terminate requests after 60s. You can disable this in your FPM pool configuration:

request_terminate_timeout = 0

Alternatively, configure a separate FPM pool specifically for SSE connections.

# Send a ping event every 30 seconds manually
php artisan sse:ping --interval=30

To customize the server-side behavior of Wave, publish the configuration file using the Artisan command. The configuration file allows you to control:

• resume_lifetime: How long (in seconds) an event stream persists to allow resumption after a reconnect. Requires a cache driver.
• retry: Milliseconds to wait before attempting a reconnect (defaults to null).
• ping: Configuration for automatic ping events to keep connections alive. Includes enable, frequency (seconds), and eager_env (an array of environments or null).
• path: The route path used for Wave connections and presence channels (defaults to wave).
• middleware: Middleware assigned to registered routes (defaults to ['web']).
• auth_middleware: Middleware used for authenticating presence channels and whisper events (defaults to auth).
• guard: The authentication guard used (defaults to web).

php artisan vendor:publish --tag="wave-config"

Wave provides a Wave class that allows you to listen to Eloquent model events and broadcast notifications using a fluent API. This respects Laravel's native conventions for Model Events Broadcasting and Broadcast Notifications.

Basic Usage

Initialize the Wave instance and use the .model() method to target a specific model by its name and primary key.

Customizing Namespaces

By default, Wave assumes models are in the App.Models namespace. You can override this during initialization using the namespace option.

import { Wave } from 'laravel-wave';

// Initialize with custom namespace if needed
window.Wave = new Wave({namespace: 'App.Path.Models'});

// Listen to events for a specific model instance
window.Wave.model('User', '1')
    .notification('team.invite', (notification) => {
        console.log(notification);
    })
    .updated((user) => console.log('user updated', user))
    .deleted((user) => console.log('user deleted', user))
    .trashed((user) => console.log('user trashed', user))
    .restored((user) => console.log('user restored', user))
    .updated('Team', (team) => console.log('team updated', team));

When initializing a Wave or Echo instance on the client side, you can pass an options object to customize the connection. Key options include:

• endpoint: The primary SSE connection route (defaults to /wave).
• namespace: The namespace of events to listen for (defaults to App.Events).
• auth.headers: An object containing additional authentication headers.
• authEndpoint: The authentication endpoint (defaults to /broadcasting/auth).
• csrfToken: The CSRF token (defaults to the XSRF-TOKEN cookie).
• bearerToken: A bearer token for authentication.
• request: Custom settings for connection and authentication requests.
• pauseInactive: If true, the connection closes when the page is hidden and reopens when visible.
• debug: If true, enables detailed event logs in the console for troubleshooting.

new Echo({
    broadcaster: WaveConnector,
    endpoint: '/sse-endpoint',
    bearerToken: 'bearer-token',
    //...
});

// or

new Wave({
    authEndpoint: '/custom-broadcasting/auth',
    csrfToken: 'csrf-token',
})