Harmonics Trait

The Harmonics trait is the foundation of Laravel Chorus. When added to your Eloquent models, it automatically tracks changes and enables real-time synchronization to connected clients.

Basic Usage

Adding the 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 Post extends Model
{
    use Harmonics;
    
    protected $fillable = [
        'title',
        'content',
        'status',
        'author_id'
    ];
}

That’s it! Your model will now automatically track changes and broadcast them to connected clients.

What the Trait Does

When you add the Harmonics trait, it automatically:

Registers event listeners for model create, update, and delete operations
Creates harmonic records in the harmonics table for each change
Broadcasts changes via WebSocket to connected clients
Provides synchronization methods for frontend integration

Defining Sync Fields

By default, no fields are synchronized for security. You must explicitly define which fields to sync using one of these methods:

Method 1: Property-Based (Recommended)

Define sync fields using a protected property:

class Post extends Model
{
    use Harmonics;
    
    protected $syncFields = [
        'id',           // Always include the primary key
        'title',
        'content',
        'status',
        'author_id',
        'created_at',
        'updated_at'
    ];
}

Method 2: Method-Based

Define sync fields using a method for simple dynamic logic:

class Post extends Model
{
    use Harmonics;
    
    public function syncFields(): array
    {
        return [
            'id',
            'title',
            'content',
            'status',
            'author_id',
            'created_at',
            'updated_at'
        ];
    }
}

Method 3: Dynamic Sync Fields

Override the getSyncFields() method for complex dynamic logic:

class Post extends Model
{
    use Harmonics;
    
    public function getSyncFields(): array
    {
        $fields = [
            'id',
            'title',
            'status',
            'created_at',
            'updated_at'
        ];
        
        // Include content only for published posts
        if ($this->status === 'published') {
            $fields[] = 'content';
        }
        
        // Include author info for authenticated users
        if (auth()->check()) {
            $fields[] = 'author_id';
        }
        
        return $fields;
    }
}

Security First: Only include fields that are safe to expose to clients. Never sync sensitive information like passwords, API keys, or internal system data.

Field Selection Best Practices

Include These Fields

✅ Always include:

Primary key (id)
User-visible data (title, name, description)
Status/state fields (status, is_active)
Relationships IDs (user_id, category_id)
Timestamps (created_at, updated_at)

Exclude These Fields

❌ Never include:

Passwords or authentication tokens
Internal system fields (internal_notes)
Sensitive personal information (ssn, credit_card)
Large binary data (file_content)
Admin-only fields (admin_notes)

Example: User Model

class User extends Model
{
    use Harmonics;
    
    // Safe fields for client synchronization
    protected $syncFields = [
        'id',
        'name',
        'email',           // OK if users can see each other's emails
        'avatar_url',
        'is_online',
        'last_seen_at',
        'created_at',
        'updated_at'
        // 'password' - NEVER include
        // 'remember_token' - NEVER include
        // 'email_verified_at' - Usually not needed
    ];
}

Automatic Change Detection

The Harmonics trait automatically detects changes using Laravel’s model events:

Create Operations

$post = Post::create([
    'title' => 'My New Post',
    'content' => 'Hello World!',
    'status' => 'draft'
]);
// ✅ Automatically creates a harmonic with operation: 'create'

Update Operations

$post = Post::find(1);
$post->update(['status' => 'published']);
// ✅ Automatically creates a harmonic with operation: 'update'

Delete Operations

$post = Post::find(1);
$post->delete();
// ✅ Automatically creates a harmonic with operation: 'delete'

Bulk Operations

Important: Bulk operations like Post::where('status', 'draft')->update(['status' => 'published']) do not trigger model events and will not be synchronized automatically.For bulk operations, you’ll need to handle synchronization manually or iterate through individual models.

Advanced Configuration

Custom Primary Keys

For models with non-standard primary keys:

class Post extends Model
{
    use Harmonics;
    
    protected $primaryKey = 'post_uuid';
    public $incrementing = false;
    protected $keyType = 'string';
    
    protected $syncFields = [
        'post_uuid',  // Include your custom primary key
        'title',
        'content'
    ];
}

Testing Your Configuration

Manual Testing

Create a test record and verify harmonics are created:

php artisan tinker

// Create a test record
$post = App\Models\Post::create([
    'title' => 'Test Post',
    'content' => 'This is a test',
    'status' => 'published',
    'author_id' => 1
]);

// Check if a harmonic was created
$harmonic = \Pixelsprout\LaravelChorus\Models\Harmonic::latest()->first();
echo $harmonic->toJson(JSON_PRETTY_PRINT);

Debug Command

Use the built-in debug command to verify your configuration:

php artisan chorus:debug

This will show:

Currently connected channels
Active user IDs

Common Issues and Solutions

No Harmonics Created

Problem: Model changes don’t create harmonic records.Solutions:

Verify the trait is added: use Harmonics;
Ensure you’re using Eloquent methods (not raw queries)
Check for exceptions in Laravel logs

Fields Not Syncing

Problem: Expected fields don’t appear in synchronized data.Solutions:

Add fields to $syncFields array
Verify fields exist in database
Check harmonics database table for change event

Too Much Data Syncing

Problem: Sync payload is too large or contains sensitive data.Solutions:

Remove unnecessary fields from $syncFields
Narrow down syncFilter query.
Implement proper filtering (covered in next section)
Consider splitting large data into separate models

Performance Issues

Problem: Model operations are slow after adding Harmonics trait.Solutions:

Use database indexes on frequently queried sync fields
Implement sync filtering to reduce harmonic volume

Next Steps

Now that your model has the Harmonics trait:

Define Sync Fields

Learn advanced field selection and dynamic sync configuration

Apply Sync Filters

Control which records are synchronized to each user

Set Up Write Actions

Configure server-side write operations and validation

Frontend Integration

Connect your frontend to synchronized models

Your model is now ready for real-time synchronization! Continue with Sync Fields to learn advanced field configuration techniques.

Overview

Integrations

Core Concepts

Advanced

Harmonics Trait

Harmonics Trait

Basic Usage

Adding the Trait

What the Trait Does

Defining Sync Fields

Method 1: Property-Based (Recommended)

Method 2: Method-Based

Method 3: Dynamic Sync Fields

Field Selection Best Practices

Include These Fields

Exclude These Fields

Example: User Model

Automatic Change Detection

Create Operations

Update Operations

Delete Operations

Bulk Operations

Advanced Configuration

Custom Primary Keys

Testing Your Configuration

Manual Testing

Debug Command

Common Issues and Solutions

Next Steps

Define Sync Fields

Apply Sync Filters

Set Up Write Actions

Frontend Integration

​Harmonics Trait

​Basic Usage

​Adding the Trait

​What the Trait Does

​Defining Sync Fields

​Method 1: Property-Based (Recommended)

​Method 2: Method-Based

​Method 3: Dynamic Sync Fields

​Field Selection Best Practices

​Include These Fields

​Exclude These Fields

​Example: User Model

​Automatic Change Detection

​Create Operations

​Update Operations

​Delete Operations

​Bulk Operations

​Advanced Configuration

​Custom Primary Keys

​Testing Your Configuration

​Manual Testing

​Debug Command

​Common Issues and Solutions

​Next Steps

Define Sync Fields

Apply Sync Filters

Set Up Write Actions

Frontend Integration

Harmonics Trait

Basic Usage

Adding the Trait

What the Trait Does

Defining Sync Fields

Method 1: Property-Based (Recommended)

Method 2: Method-Based

Method 3: Dynamic Sync Fields

Field Selection Best Practices

Include These Fields

Exclude These Fields

Example: User Model

Automatic Change Detection

Create Operations

Update Operations

Delete Operations

Bulk Operations

Advanced Configuration

Custom Primary Keys

Testing Your Configuration

Manual Testing

Debug Command

Common Issues and Solutions

Next Steps