Laravel Database Sync

A lightweight Laravel package for automatic database synchronization via HTTP requests. This package automatically detects database changes in your Eloquent models and sends them to an external synchronization service.

Features

🔄 Automatic Sync: Automatically syncs database changes via HTTP requests
🚀 Model Discovery: Automatically discovers and registers Eloquent models
📊 Event-Driven: Uses Laravel model events for real-time synchronization
🛡️ Data Sanitization: Automatically removes sensitive fields before syncing
⚙️ Configurable: Easy configuration for endpoints, timeouts, and filters
🔧 Artisan Commands: CLI tools for model discovery and status checking
📝 Comprehensive Logging: Detailed logging for debugging and monitoring

Installation

Via Composer

composer require obalaweb/laravel-database-sync

Manual Installation

Clone this repository into your project:

git clone https://github.com/obalaweb/laravel-database-sync.git packages/laravel-database-sync

Add the package to your composer.json:

{
    "require": {
        "obalaweb/laravel-database-sync": "*"
    },
    "repositories": [
        {
            "type": "path",
            "url": "packages/laravel-database-sync"
        }
    ]
}

Run composer update:

composer update

Configuration

Publishing Configuration

Publish the configuration file:

php artisan vendor:publish --provider="LaravelDatabaseSync\DatabaseSyncServiceProvider" --tag="config"

This will create config/database-sync.php with all available options.

Environment Variables

Add these to your .env file:

# Enable/disable database sync
DATABASE_SYNC_ENABLED=true

# Sync service endpoint
DATABASE_SYNC_ENDPOINT=http://localhost:8080/sync-record

# Request timeout in seconds
DATABASE_SYNC_TIMEOUT=5

Configuration Options

// config/database-sync.php
return [
    // Enable or disable database sync
    'enabled' => env('DATABASE_SYNC_ENABLED', false),

    // HTTP endpoint for sync service
    'endpoint' => env('DATABASE_SYNC_ENDPOINT', 'http://localhost:8080/sync-record'),

    // Request timeout in seconds
    'timeout' => env('DATABASE_SYNC_TIMEOUT', 5),

    // Directories to scan for models
    'model_paths' => [
        app_path('Models'),
        app_path(),
    ],

    // Explicitly define models to sync (optional)
    'models' => [
        // App\Models\User::class,
        // App\Models\Post::class,
    ],

    // Only sync these tables (empty = all tables)
    'tables' => [
        // 'users',
        // 'posts',
    ],

    // Skip these tables
    'skip_tables' => [
        'migrations',
        'password_resets',
        'failed_jobs',
        'sync_queue',
        'sessions',
        'cache',
        'jobs',
    ],

    // Skip these fields from sync data
    'skip_fields' => [
        'password',
        'remember_token',
        'api_token',
        'email_verified_at',
    ],
];

Usage

Automatic Setup

Once installed and configured, the package will automatically:

Discover all Eloquent models in your application
Register event listeners for created, updated, and deleted events
Send HTTP requests to your sync service when database changes occur

Making Models Syncable (Optional)

For advanced control, you can implement the SyncableModelInterface:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use LaravelDatabaseSync\Contracts\SyncableModelInterface;
use LaravelDatabaseSync\Traits\SyncableModel;

class User extends Model implements SyncableModelInterface
{
    use SyncableModel;

    protected $fillable = [
        'name',
        'email',
        'password',
    ];

    /**
     * Get data that should be synchronized
     */
    public function getSyncableData(): array
    {
        $data = $this->toArray();

        // Customize what data gets synced
        unset($data['password']);
        unset($data['remember_token']);

        return $data;
    }

    /**
     * Determine if this model should be synchronized
     */
    public function shouldSync(): bool
    {
        // Only sync active users
        return $this->status === 'active';
    }
}

Disabling Sync for Specific Models

You can disable sync for specific models by adding a $disableSync property:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class InternalLog extends Model
{
    // Disable sync for this model
    protected $disableSync = true;

    protected $fillable = [
        'message',
        'level',
    ];
}

Artisan Commands

Discover Models

# Discover all Eloquent models in your application
php artisan db:sync discover

Register Models for Sync

# Register all discovered models for sync
php artisan db:sync register

Check Sync Status

# Check sync configuration and registered models
php artisan db:sync status

Programmatic Usage

<?php

use LaravelDatabaseSync\Services\DatabaseSyncService;
use LaravelDatabaseSync\Services\AutoSyncService;

class SyncController extends Controller
{
    public function __construct(
        private DatabaseSyncService $syncService,
        private AutoSyncService $autoSyncService
    ) {}

    public function registerModels()
    {
        $this->autoSyncService->registerAllModels();
        
        $registered = $this->autoSyncService->getRegisteredModels();
        
        return response()->json([
            'message' => 'Models registered for sync',
            'count' => count($registered),
            'models' => $registered,
        ]);
    }

    public function manualSync()
    {
        // Manually sync a record
        $success = $this->syncService->recordInsert('users', [
            'id' => 1,
            'name' => 'John Doe',
            'email' => '[email protected]',
        ]);

        return response()->json([
            'success' => $success,
        ]);
    }
}

Sync Service Integration

The package sends HTTP POST requests to your sync service with the following structure:

Request Format

{
    "table_name": "users",
    "operation": "INSERT|UPDATE|DELETE",
    "data": {
        "id": 1,
        "name": "John Doe",
        "email": "[email protected]",
        "created_at": "2025-01-15T10:30:00.000000Z",
        "updated_at": "2025-01-15T10:30:00.000000Z"
    }
}

Operations

INSERT: Sent when a new record is created
UPDATE: Sent when an existing record is updated
DELETE: Sent when a record is deleted (only includes the ID)

Example Sync Service (Node.js)

const express = require('express');
const app = express();

app.use(express.json());

app.post('/sync-record', (req, res) => {
    const { table_name, operation, data } = req.body;
    
    console.log(`Sync: ${operation} on ${table_name}`, data);
    
    // Process the sync data
    // Store in external database, send to API, etc.
    
    res.json({ success: true });
});

app.listen(8080, () => {
    console.log('Sync service running on port 8080');
});

Advanced Configuration

Custom Model Discovery

// config/database-sync.php
'model_paths' => [
    app_path('Models'),
    app_path('Domain/Models'),
    app_path('App/Models'),
],

Selective Table Sync

// config/database-sync.php
'tables' => [
    'users',
    'posts',
    'comments',
],

Custom Field Filtering

// config/database-sync.php
'skip_fields' => [
    'password',
    'remember_token',
    'api_token',
    'email_verified_at',
    'deleted_at',
],

Logging

The package logs all sync operations. Check your Laravel logs for:

Debug: Successful sync requests
Warning: Failed HTTP requests
Error: Exceptions and connection errors

# View sync logs
tail -f storage/logs/laravel.log | grep "Sync"

Testing

# Run tests
composer test

# Run tests with coverage
composer test-coverage

Troubleshooting

Sync Not Working

Check if sync is enabled:
```
php artisan db:sync status
```

Verify your endpoint is accessible:

curl -X POST http://localhost:8080/sync-record

Check Laravel logs for errors:
```
tail -f storage/logs/laravel.log
```

Models Not Being Discovered

Run model discovery:
```
php artisan db:sync discover
```
Check your model paths configuration
Ensure models extend Illuminate\Database\Eloquent\Model

Performance Issues

Increase timeout in configuration
Consider using queue workers for sync requests
Monitor memory usage during large sync operations

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

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

Support

If you encounter any issues or have questions, please:

Check the documentation
Search existing issues
Create a new issue

Changelog

Please see CHANGELOG.md for more information on what has changed recently.

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
src		src
.gitignore		.gitignore
README.md		README.md
composer.json		composer.json
composer.lock		composer.lock

obalaweb/laravel-database-sync

Folders and files

Latest commit

History

Repository files navigation