Getting Started

This guide will walk you through installing and configuring Laravel Chorus in your Laravel application. You’ll have real-time synchronization working in under 10 minutes.

Prerequisites

Before you begin, ensure you have:

Laravel 10+ application
PHP 8.1+
Laravel Reverb (for WebSocket connections)
Node.js 18+ (for frontend integration)

Quick Start

The easiest way to get started is by using the React Starter Kit for Chorus. This starter kit is based on Laravel’s React Starter Kit, but with Chorus pre-installed and a simple example included, so you can hit the ground running. To get started, run this command in your favorite terminal:

laravel new chorus-starter-test --using=pixelsprout/chorus-react-starter-kit

You will be prompted to set up Reverb as your broadcast driver and set up Chorus’s dependencies. Now run the following in your favorite terminal in the root project directory:

# Terminal 1
composer run dev # runs vite, composer, queues all in one

# Terminal 2
php artisan reverb:start # Start the reverb server to start syncing your data in real-time

After installing and running the servers, log in/sign up to the dashboard as a user. You will now see that we have set up the users table to be synced. Now to test how awesome sync is, open a terminal in the root project directory and enter the following:

php artisan tinker

$user = User::first()
$user->name = 'Taylor Otwell'
$user->save()

Did you see that? Our data is updated in real-time! Try experimenting with creating and deleting users, and watch the users update live in the browser. Chorus also provides a method to write data locally and subsequently sync the data to the server. You can learn more by looking at the Write Path documentation.

How to install into an existing Laravel App

Step 1: Install the Package

Install Laravel Chorus via Composer:

composer require pixelsprout/laravel-chorus

Step 2: Run the Installer

The installer sets up everything you need:

php artisan chorus:install

This command will:

Publish configuration files
Create the harmonics database migration
Set up Laravel Reverb (if not already installed)
Generate TypeScript utilities in resources/js/chorus
Configure broadcasting settings
Install the appropriate Chorus package for your chosen framework

Step 3: Run Migrations

Create the harmonics table:

php artisan migrate

Configuration

Database Configuration

The config/chorus.php file contains all Chorus settings:

<?php

return [
    // Channel prefix resolver for multi-tenancy
    'channel_prefix_resolver' => null, // e.g., App\Chorus\Resolvers\TenantPrefixResolver::class

    // Where to recive change events (default: eloquent).
    "harmonic_source_adapter" => env(
        "CHORUS_HARMONIC_SOURCE_ADAPTER",
        "eloquent"
    ),

    // What prefix and middleware to apply on chorus API routes.
    "routes" => [
        "prefix" => "api",
        "middleware" => ["web", "api"],
    ],
];

Your First Synchronized Model

Step 1: Add the Harmonics Trait

Add the Harmonics trait to any model you want to synchronize:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Pixelsprout\LaravelChorus\Traits\Harmonics;

class Message extends Model
{
    use Harmonics;
    
    protected $fillable = [
        'title',
        'body', 
        'user_id',
        'status'
    ];
    
    // Define which fields to synchronize
    protected $syncFields = [
        'id',
        'title', 
        'body',
        'user_id',
        'status',
        'created_at',
        'updated_at'
    ];
    
    // Optional: Filter which records to sync per user
    protected function syncFilter()
    {
        return $this->where('user_id', auth()->id());
    }
}

Step 2: Create Write Actions

Generate write actions for your model:

php artisan chorus:make-write-action CreateMessageAction

This creates action classes in app/Actions/WriteActions/:

<?php

namespace App\Actions\WriteActions;

use App\Models\Message;
use Illuminate\Http\Request;
use Pixelsprout\LaravelChorus\Support\WriteAction;

class CreateMessageAction extends WriteAction
{
    protected array $config = [
        'allowOfflineWrites' => true,
        'supportsBatch' => false,
    ];

    public function handle(Request $request, array $data): Message
    {
        return Message::create([
            'id' => $data['id'] ?? null,
            'title' => $data['title'],
            'body' => $data['body'],
            'user_id' => auth()->id(),
            'status' => $data['status'] ?? 'draft',
        ]);
    }

    public function rules(): array
    {
        return [
            'title' => 'required|string|max:255',
            'body' => 'required|string',
            'status' => 'in:draft,published',
            'id' => 'nullable|string|uuid',
        ];
    }
}

class Message extends Model
{
    use Harmonics;
    
    // ... other code ...
    
    protected $writeActions = [
        'create' => CreateMessageAction::class,
        'update' => UpdateMessageAction::class,
        'delete' => DeleteMessageAction::class,
    ];
}

Step 3: Update Model Configuration

Add your model to the config/chorus.php:

'models' => [
    'messages' => App\Models\Message::class,
],

Frontend Integration

Step 1: Add the Chorus Provider

Wrap your app with the Chorus provider:

// resources/js/app.tsx
import { ChorusProvider } from '@/chorus/react';

function App() {
    return (
        <ChorusProvider
            userId={user.id}
            channelPrefix={user.tenant_id} // Optional for multi-tenancy
        >
            <YourAppComponents />
        </ChorusProvider>
    );
}

Step 2: Use Data in Components

Use Chorus hooks to access synchronized data:

// resources/js/components/MessagesList.tsx
import { useTable } from '@pixelsprout/chorus-react';
import { Message } from '@stores/types';

export default function MessagesList() {
    const { 
        data: messages, 
        create, 
        update, 
        remove,
        isLoading,
        error 
    } = useTable<Message>('messages');
    
    const handleCreateMessage = async () => {
        await create(
            // Optimistic data for instant UI update
            {
                id: crypto.randomUUID(),
                title: 'New Message',
                body: 'Hello world!',
                user_id: user.id,
                status: 'draft',
                created_at: new Date(),
                updated_at: new Date(),
            },
            // Data sent to server
            {
                title: 'New Message',
                body: 'Hello world!',
            }
        );
    };
    
    if (isLoading) return <div>Loading...</div>;
    if (error) return <div>Error: {error}</div>;
    
    return (
        <div>
            <button onClick={handleCreateMessage}>
                Create Message
            </button>
            
            {messages?.map((message) => (
                <div key={message.id}>
                    <h3>{message.title}</h3>
                    <p>{message.body}</p>
                    <small>Status: {message.status}</small>
                </div>
            ))}
        </div>
    );
}

Start the Servers

Start Reverb

Start the Laravel Reverb WebSocket server:

php artisan reverb:start

Start Your Frontend

composer run dev

Testing Your Integration

Open multiple browser tabs to your application
Create, update, or delete messages in one tab
Watch changes appear instantly in other tabs
Go offline and make changes - they’ll sync when back online

Next Steps

Harmonics Trait

Add the Harmonics trait to your models

React Integration

Build real-time React components

Write Actions

Master server-side write operations and validation

Advanced Features

Set up multi-tenancy and advanced features

Troubleshooting

WebSocket Connection Issues

Ensure Reverb is properly configured and running. Check the browser console for connection errors. You can also run reverb with the --debug flag to see when harmonic events get fired.

Changes Not Syncing

Verify the model has the Harmonics trait. Check server logs for errors.

Offline Writes Failing

Ensure write actions have allowOfflineWrites => true and proper validation rules.

Type Errors in Frontend

Run php artisan chorus:generate --types to regenerate TypeScript definitions.

Congratulations! You now have Laravel Chorus running in your application. Your users will experience instant, real-time updates with full offline support.

Overview

Integrations

Core Concepts

Advanced

Prerequisites

Quick Start

How to install into an existing Laravel App

Step 1: Install the Package

Step 2: Run the Installer

Step 3: Run Migrations

Configuration

Database Configuration

Your First Synchronized Model

Step 1: Add the Harmonics Trait

Step 2: Create Write Actions

Step 3: Update Model Configuration

Frontend Integration

Step 1: Add the Chorus Provider

Step 2: Use Data in Components

Start the Servers

Start Reverb

Start Your Frontend

Testing Your Integration

Next Steps

Harmonics Trait

React Integration

Write Actions

Advanced Features

Troubleshooting

​Prerequisites

​Quick Start

​How to install into an existing Laravel App

​Step 1: Install the Package

​Step 2: Run the Installer

​Step 3: Run Migrations

​Configuration

​Database Configuration

​Your First Synchronized Model

​Step 1: Add the Harmonics Trait

​Step 2: Create Write Actions

​Step 3: Update Model Configuration

​Frontend Integration

​Step 1: Add the Chorus Provider

​Step 2: Use Data in Components

​Start the Servers

​Start Reverb

​Start Your Frontend

​Testing Your Integration

​Next Steps

Harmonics Trait

React Integration

Write Actions

Advanced Features

​Troubleshooting

Prerequisites

Quick Start

How to install into an existing Laravel App

Step 1: Install the Package

Step 2: Run the Installer

Step 3: Run Migrations

Configuration

Database Configuration

Your First Synchronized Model

Step 1: Add the Harmonics Trait

Step 2: Create Write Actions

Step 3: Update Model Configuration

Frontend Integration

Step 1: Add the Chorus Provider

Step 2: Use Data in Components

Start the Servers

Start Reverb

Start Your Frontend

Testing Your Integration

Next Steps

Troubleshooting