Download the PHP package 7amoood/laravel-appsync-broadcaster without Composer

Laravel AppSync Broadcaster

A Laravel broadcasting driver for AWS AppSync that supports two publishing modes (direct, redis) and two transports (http, websocket) for real-time event delivery.

Features

• Two publishing modes: publish directly from Laravel or queue through Redis
• Two transport layers: send via HTTP or a persistent WebSocket connection
• Background worker support: php artisan appsync:worker relays Redis events to AppSync
• Channel support: public, private, and presence channels
• Authentication: Cognito-based auth for secured channels
• Retry, buffering, and back-pressure controls
• Frontend integration: WebSocket subscription examples for JavaScript and browsers
• Laravel integration: plugs into Laravel's native broadcasting system

Installation

Install the package via Composer:

The service provider is auto-discovered by Laravel.

Configuration

1. Publish the configuration file:

2. Set AppSync as your default broadcast driver and configure the core variables in .env:

3. Optional tuning values from config/appsync.php:

Note: The AppSync connection is registered automatically. You do not need to manually add it to config/broadcasting.php.

Modes

Transports

Supported combinations

Worker Usage (redis mode)

If you choose APPSYNC_MODE=redis, you must run the worker process:

Common overrides:

Production note: Run the worker under Supervisor or systemd in production.

Usage

Basic Broadcasting

Use Laravel's standard broadcasting flow:

Presence Channels

For presence channels, use Laravel's PresenceChannel as usual:

How publishing works

• direct mode: your Laravel request publishes to AppSync immediately.
• redis mode: your Laravel request only pushes the event to Redis, and the worker handles delivery.
• http transport: uses HTTP requests with retry and exponential backoff.
• websocket transport: keeps a live connection open and batches events efficiently.

Channel Authentication

For private and presence channels, define authorization logic in routes/channels.php:

Frontend Integration

To subscribe to channels from your frontend application, you need to establish a WebSocket connection to AWS AppSync. Here's how to do it:

JavaScript/Node.js Example

Browser Example (ES6+)

Channel Name Format

Channels follow this format: {namespace}/{channel_type}-{channel_name}

• namespace: From your APPSYNC_NAMESPACE config (default: "default")
• channel_type:
  • public for public channels
  • private for private channels
  • presence for presence channels
• channel_name: Your channel identifier

Examples:

• default/orders (public channel)
• default/private-user/123 (private channel)
• default/presence-chat/room1 (presence channel)

Authentication Flow

1. Frontend sends channel name to your Laravel app's /broadcasting/auth endpoint
2. Laravel validates the request and returns an AppSync API key
3. Frontend uses the API key to establish WebSocket connection
4. Frontend subscribes to specific channels using the authenticated connection

Event Structure

Events received from AppSync have this structure:

AWS AppSync Setup

1. Create an AppSync Event API in your AWS Console
2. Set up Cognito User Pool for authentication
3. Create a Cognito App Client with client credentials flow enabled
4. Attach Cognito to AppSync as auth method

Error Handling

The broadcaster includes built-in protections for both direct and worker-based delivery:

• HTTP retry logic with exponential backoff and jitter
• Token refresh handling for expired or invalid auth tokens
• Partial failure handling so one failed channel does not stop the rest
• WebSocket reconnect/buffering support for long-lived connections
• Worker buffer limits and stats logging in redis mode

Logging

Important lifecycle and failure details are logged through Laravel's logging system, including:

• Authentication failures
• HTTP retry attempts
• WebSocket disconnects/reconnects
• Redis worker publish/drop statistics
• Configuration and transport errors

Requirements

• PHP ^8.0
• Laravel ^9.0|^10.0|^11.0
• AWS AppSync API
• AWS Cognito User Pool
• Redis server (only when using APPSYNC_MODE=redis)

License

This package is open-sourced software licensed under the MIT license.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security-related issues, please email the package maintainer instead of using the issue tracker.