README

Legacy Sync is a lightweight Laravel package for bi-directional database syncing between a legacy and modern app. It’s ideal for projects maintaining both a legacy and a modern Laravel app, and ensures data consistency across both systems without friction.

🚀 Features

🔄 Bi-directional database syncing between legacy and modern applications
🗄️ Flexible table and column mapping configuration
🧩 Support for different database column names and structures
⚙️ Customizable field defaults and exclusions
🌍 Shared, environment-agnostic logic — install on both apps
🔍 Efficient processing with lazy loading for large datasets

🧩 Requirements

To use Legacy Sync, the package must be installed in both Laravel applications you wish to sync.

Legacy Sync is compatible with applications using Laravel 8 and above, and requires PHP 8.1 or above.

📦 Installation

Legacy Sync must be installed in both your legacy app and the modern app.

composer require clarkewing/legacy-sync

Make sure you configure your database connections in your application’s config/database.php file:

// config/database.php
'connections' => [
    // Your default connection...
    
    'legacy' => [
        'driver' => 'mysql',
        'host' => env('DB_LEGACY_HOST', 'localhost'),
        'port' => env('DB_LEGACY_PORT', '3306'),
        'database' => env('DB_LEGACY_DATABASE', 'legacy_db'),
        'username' => env('DB_LEGACY_USERNAME', 'root'),
        'password' => env('DB_LEGACY_PASSWORD', ''),
        'charset' => 'utf8mb4',
        // ...other database configuration options
    ],
],

⚙️ Configuration

Publish the config file using the following command:

php artisan vendor:publish --tag=legacy-sync-config

This will create a config/legacy_sync.php file with the following structure:

return [
    /*
    |--------------------------------------------------------------------------
    | Database connections
    |--------------------------------------------------------------------------
    |
    | Here you should specify the connections used for syncing.
    | These should reference connection names defined in your config/database.php file.
    |
    */

    'connections' => [
        'legacy' => 'legacy', // References the 'legacy' connection in database.php
        'new' => 'sqlite',    // References the 'sqlite' connection in database.php
    ],

    /*
    |--------------------------------------------------------------------------
    | Legacy database sync mapping
    |--------------------------------------------------------------------------
    |
    | Here you should specify the mapping and defaults used for syncing
    | the legacy and new databases of your app.
    | Expected format:
    | 'table_name' => [
    |    'map' => [
    |        'legacy_column_name' => 'new_column_name',
    |        // Columns which share the same name in databases are implicitly mapped 1:1.
    |        // One-sided fields which aren't explicitly mapped and don't have a default are omitted from the sync.
    |    ],
    |    // Defaults for optional fields that exist only in the new or legacy table
    |    'defaults' => [
    |        'reputation' => 0,
    |    ],
    |    // Exclude fields that don't exist in one database to avoid errors
    |    'exclude' => [
    |        'legacy' => ['missing_from_legacy'],
    |        'new' => ['missing_from_new'],
    |    ],
    |
    */

    'mapping' => [
        'users' => [
            'primary_key' => 'id',

            'map' => [
                'birthdate' => 'birth_date',
            ],
        ],
    ],
];

🔧 Usage

Syncing Tables

Legacy Sync provides a simple API for syncing tables between your legacy and modern applications:

use ClarkeWing\LegacySync\Facades\LegacySync;
use ClarkeWing\LegacySync\Enums\SyncDirection;

// Sync a specific table from legacy to new
LegacySync::syncTable('users', SyncDirection::LegacyToNew);

// Sync a specific table from new to legacy
LegacySync::syncTable('users', SyncDirection::NewToLegacy);

// Sync all configured tables from legacy to new
LegacySync::syncAll(SyncDirection::LegacyToNew);

// Sync all configured tables from new to legacy
LegacySync::syncAll(SyncDirection::NewToLegacy);

Syncing Individual Records

For more granular control, you can sync individual records by their primary key:

use ClarkeWing\LegacySync\Facades\LegacySync;
use ClarkeWing\LegacySync\Enums\SyncDirection;

// Sync a specific user with ID 123 from legacy to new
LegacySync::syncRecord('users', 123, SyncDirection::LegacyToNew);

// Sync a specific user with ID 456 from new to legacy
LegacySync::syncRecord('users', 456, SyncDirection::NewToLegacy);

Artisan Commands

Legacy Sync also provides an Artisan command for syncing tables:

# Sync all tables from legacy to new
php artisan legacy:sync legacy_to_new

# Sync all tables from new to legacy
php artisan legacy:sync new_to_legacy

# Sync a specific table from legacy to new
php artisan legacy:sync legacy_to_new --table=users

# Sync a specific table from new to legacy
php artisan legacy:sync new_to_legacy --table=users

Configuration Examples

Basic Column Mapping

When column names differ between legacy and new databases:

'users' => [
    'primary_key' => 'id',
    'map' => [
        'legacy_column_name' => 'new_column_name',
        'user_name' => 'username',
        'birth_date' => 'birthdate',
        'email_address' => 'email',
    ],
],

Setting Default Values

For columns that exist in only one database:

'users' => [
    'primary_key' => 'id',
    'map' => [
        'user_name' => 'username',
    ],
    'defaults' => [
        'active' => true,
        'verified' => false,
    ],
],

Excluding Columns

To exclude specific columns from syncing:

'users' => [
    'primary_key' => 'id',
    'exclude' => [
        'legacy' => ['password_hash', 'remember_token'],
        'new' => ['password', 'two_factor_secret'],
    ],
],

🧪 Testing

You can safely prevent real database syncing during tests by faking the facade. When faked, all sync methods become no-ops and no database writes will occur.

LegacySync::fake() swaps the facade to a fake implementation.
LegacySync::isFake() lets you detect if the facade is currently faked.

Example (Pest):

use ClarkeWing\LegacySync\Enums\SyncDirection;
use ClarkeWing\LegacySync\Facades\LegacySync;

it('does not perform real syncing when faked', function () {
    // Prevent any actual syncing work
    LegacySync::fake();

    expect(LegacySync::isFake())->toBeTrue();

    // These calls are intercepted and do nothing
    LegacySync::syncAll(SyncDirection::LegacyToNew);
    LegacySync::syncTable('users', SyncDirection::NewToLegacy);
    LegacySync::syncRecord('users', 123, SyncDirection::LegacyToNew);
});

You can also fake before invoking your own application code or Artisan commands that trigger syncing:

use ClarkeWing\LegacySync\Facades\LegacySync;

LegacySync::fake();

// For example, a feature test that triggers a sync via a command
$this->artisan('legacy:sync legacy_to_new')
    ->assertSuccessful();

Note: The provided fake is intentionally a safe no-op and does not record calls for assertions. If you need to assert specific interactions, mock your own collaborators or assert application-side effects instead of database changes.

🔐 Security

When syncing sensitive data between databases, ensure both systems have appropriate security measures in place. Consider excluding sensitive fields from syncing or implementing additional encryption as needed.

🤝 Contributing

Issues and PRs welcome! Please see our Contribution guidelines if contributing tests or features.

📜 License

Released under the MIT License.

clarkewing / legacy-sync

Maintainers

Details