Skip to main content

​
Harmonics

Harmonics are the fundamental units of change in Laravel Chorus. Every create, update, or delete operation on a synchronized model generates a harmonic record that captures what changed and broadcasts it to connected clients.

​
What is a Harmonic?

A harmonic is a change record stored in the harmonics database table that contains:
  • What changed - The table name and record ID
  • How it changed - The operation type (create/update/delete)
  • The new data - JSON payload of the synchronized fields
  • Who can see it - Optional user_id for scoped synchronization (mainly used for rejected harmonics)
  • When it happened - Timestamp for ordering and deduplication
// Example harmonic record
{
    "id": 1,
    "table_name": "messages",
    "record_id": "123",
    "operation": "create",
    "data": {
        "id": "123",
        "body": "Hello world!",
        "user_id": 1,
        "created_at": "2024-01-15T10:30:00Z"
    },
    "user_id": 1,
    "created_at": "2024-01-15T10:30:00Z"
}

​
The Harmonic Lifecycle

​
1. Change Detection

1

Change Detection

When a model with the Harmonics trait is modified, Laravel’s model events automatically detect the change:
class Message extends Model
{
    use Harmonics;

    protected $syncFields = ['id', 'body', 'user_id'];
}

// This triggers harmonic creation
$message = Message::create([
'body' => 'Hello world!',
'user_id' => 1
]);
2

Harmonic Creation

The trait’s event listeners create a harmonic record.
3

Broadcasting

The harmonic is immediately broadcast via WebSocket to connected clients.
4

Client Processing

Connected clients receive the harmonic and update their local IndexedDB.

​
Data Filtering in Harmonics

​
Field Filtering

Only fields defined in $syncFields are included in harmonic data: 
class User extends Model
{
    use Harmonics;
    
    // Only these fields will appear in harmonics
    protected $syncFields = [
        'id',
        'name', 
        'email',
        'avatar_url'
        // 'password' excluded for security
        // 'remember_token' excluded for security
    ];
}

​
Best Practices

​
Performance Optimization

  • Only sync essential fields
  • Use computed fields sparingly
  • Avoid large text or binary data
  • Consider separate models for large content
  • Use database indexes for sync filters
  • Avoid complex relationship queries in filters
  • Cache expensive filter computations
  • Use appropriate data types for filter fields
  • Use bulk operations when possible
  • Implement batch harmonic creation for imports
  • Consider background processing for large datasets
  • Use database transactions for consistency

​
Security Considerations

  • Never sync sensitive data (passwords, tokens)
  • Validate sync fields at runtime
  • Use field whitelisting, not blacklisting
  • Regular security audits of synced data
  • Always implement sync filters for user data
  • Validate user permissions in filters
  • Use tenant-based isolation for multi-tenant apps
  • Test authorization thoroughly
  • Validate harmonic data before broadcasting
  • Sanitize data for client consumption
  • Implement server-side validation for all operations
  • Use type checking for harmonic payloads
  • Use Laravel policies to control harmonic access
  • Implement view() method to filter unauthorized harmonics
  • Leverage existing authorization logic
  • Automatic rejection of unauthorized changes

​
Next Steps

Write Path

Learn how client writes are processed and validated

Shadow Tables

Understand offline synchronization with shadow tables

React Integration

Use harmonics in your React components

Advanced Features

Explore advanced harmonic routing and channels
Harmonics are the foundation that makes Laravel Chorus’s real-time synchronization possible. Understanding how they work will help you design efficient, secure, and scalable real-time applications.