README

Pull the production database and storage assets from a remote Laravel environment to your local setup — no FTP, no SSH, just one artisan command.

How It Works

1. The package exposes protected endpoints on your remote site.
2. sync:pull downloads a gzipped mysqldump of the remote database and imports it into your local database.
3. For assets, it compares local and remote files via hash manifests and streams only new, changed, and deleted files as compressed tar.gz archives.

First run downloads everything. Subsequent asset runs only sync the diff.

Requirements

• PHP 8.1+
• Laravel 10, 11, 12, or 13
• MySQL / MariaDB
• mysqldump, mysql, gzip/gunzip, and tar available on the relevant machines (standard on Linux/macOS)

Installation

Install the package on both your local and remote environments:

composer require marceli-to/laravel-sync

Configuration

Publish the config (optional — defaults work out of the box):

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

Environment Variables

Both environments (local + remote):

LARAVEL_SYNC_TOKEN=your-shared-secret-here

Generate a secure token:

openssl rand -hex 32

Local environment only:

LARAVEL_SYNC_REMOTE=https://your-production-site.com

Usage

Pull everything (database + assets)

php artisan sync:pull

Pull only the database

php artisan sync:pull --only=database

Pull only assets

php artisan sync:pull --only=assets

Dry run (see what would change)

php artisan sync:pull --dry-run

Force full asset sync (skip delta comparison)

php artisan sync:pull --full

Skip confirmation prompts

php artisan sync:pull --force

Safety

Importing the remote database overwrites your local database. To protect against accidents:

• The command refuses to run if the local APP_ENV is production.
• It asks for confirmation before importing (skip with --force).
• Database credentials are passed via a temporary --defaults-extra-file, so they never appear in the process list.

Configuration Options

// config/laravel-sync.php

return [
    // Shared secret for authentication (required on both sides)
    'token' => env('LARAVEL_SYNC_TOKEN', ''),

    // Remote URL to pull from (local side only)
    'remote' => env('LARAVEL_SYNC_REMOTE', ''),

    // Database connection to dump/import (null = default). MySQL only.
    'connection' => env('LARAVEL_SYNC_CONNECTION'),

    // Asset directories to sync (relative to project root).
    // Add entries to limit the sync to specific sub-folders.
    'paths' => [
        'assets' => 'storage/app/public',
    ],

    // URL prefix for the sync endpoints
    'route_prefix' => '_sync',

    // Optional IP whitelist (empty = allow all, token still required)
    'allowed_ips' => [],
];

Updating

composer update marceli-to/laravel-sync

Remember to update on both local and remote when upgrading.

Security

• All requests require a valid bearer token (compared in constant time).
• The /_sync/database endpoint can stream your entire database — use a strong, unique token and consider the IP whitelist.
• Optional IP whitelisting for additional protection.
• Directory traversal protection on asset file serving.

License

MIT