S3 Move for Laravel

A Laravel package to migrate files from local storage to Amazon S3 or S3-compatible storage with smart duplicate detection.

Features

• Laravel 10, 11, and 12 compatible
• PHP 8.1+ support
• Migrate files from local storage to S3
• Smart duplicate detection - automatically skips files that already exist on S3
• Configurable file extensions filter
• Progress bar for migration tracking
• Detailed migration statistics (migrated, skipped, total)
• Event-driven architecture (fires event on completion)
• Optional local file deletion after migration
• Works with S3-compatible storage (DigitalOcean Spaces, MinIO, etc.)

Installation

Install the package via Composer:

composer require xerxes/s3-move

Publish Configuration

php artisan vendor:publish --tag=s3move-config

This will create config/s3move.php.

Configuration

Edit config/s3move.php:

return [
    // Paths to scan for files
    'local_paths' => [
        storage_path('app/public'),
        public_path('img'),
        public_path('images'),
    ],

    // File extensions to migrate
    'extensions' => [
        'jpg', 'jpeg', 'png', 'gif', 'webp', 'svg',
        'pdf', 'mp4', 'mov', 'doc', 'docx', 'zip',
    ],

    // S3 bucket name
    'aws_bucket' => env('AWS_BUCKET'),

    // S3 path prefix
    'aws_bucket_path' => env('AWS_BUCKET_PATH', '/'),
];

Ensure your .env has S3 credentials:

AWS_ACCESS_KEY_ID=your-key-id
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=your-bucket-name
AWS_ENDPOINT=https://your-endpoint.com  # Optional for S3-compatible storage

Usage

Basic Migration (Skips Duplicates)

By default, the command will skip files that already exist on S3:

php artisan s3:move

You'll be prompted to confirm before the migration starts.

Force Migration (No Confirmation)

php artisan s3:move --force

Overwrite Existing Files

If you want to replace files that already exist on S3:

php artisan s3:move --overwrite

Delete Local Files After Migration

php artisan s3:move --delete

Warning: Use --delete with caution. Files will be permanently deleted from local storage.

Combined Options

# Skip duplicates, no confirmation, delete local files after upload
php artisan s3:move --force --delete

# Overwrite existing files, no confirmation
php artisan s3:move --force --overwrite

Migration Output

The command provides detailed statistics:

═══════════════════════════════════════
          Migration Summary
═══════════════════════════════════════
┌────────────────────────────┬───────┐
│ Metric                     │ Count │
├────────────────────────────┼───────┤
│ Total Files                │ 150   │
│ ✓ Migrated                 │ 45    │
│ ⊘ Skipped (Already Exist)  │ 105   │
└────────────────────────────┴───────┘
✓ Migration completed successfully!
⊘ 105 file(s) were skipped because they already exist on S3
  Use --overwrite flag to replace existing files

Events

The package fires a S3MigrationCompleted event after migration finishes. You can listen to this event to perform custom actions:

// In your EventServiceProvider
protected $listen = [
    \Xerxes\S3Move\Events\S3MigrationCompleted::class => [
        YourListener::class,
    ],
];

// YourListener.php
public function handle(S3MigrationCompleted $event)
{
    // $event->migratedFiles contains the collection of migrated files
    foreach ($event->migratedFiles as $file) {
        // Update database records, clean up, etc.
    }
}

Requirements

• PHP 8.1 or higher
• Laravel 10.0, 11.0, or 12.0
• AWS S3 or S3-compatible storage

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

The MIT License (MIT). Please see License File for more information.