README

A sleek Laravel package that wraps rclone with an elegant, fluent API syntax.

👁 PHP Version
👁 Laravel Version
👁 Test Coverage
👁 Total Downloads

✨ Features

• 🎯 Fluent API - Laravel-style method chaining
• 🚀 Driver Agnostic - Local, S3, SFTP, FTP support
• ⚡ Zero Configuration - Uses Laravel filesystem config
• 🔧 Highly Configurable - Override any rclone option
• 📊 Progress Tracking - Real-time callbacks & stats
• 🧪 100% Test Coverage - Battle-tested with Pest
• 🏗️ Laravel Native - Service Provider, Facade, Auto-Discovery

🚀 Quick Start

Install via Composer:

composer require innoge/laravel-rclone

Basic usage:

use InnoGE\LaravelRclone\Facades\Rclone;

// Simple sync
Rclone::source('s3', 'documents')
 ->target('backup', 'archive')
 ->sync();

// With progress & options
Rclone::source('s3', 'media/photos')
 ->target('local', 'storage/backups')
 ->withProgress()
 ->transfers(16)
 ->checkers(8)
 ->getOutputUsing(fn($type, $output) => Log::info("Rclone: {$output}"))
 ->sync();

📋 Requirements

• PHP 8.2+
• Laravel 10.x, 11.x, or 12.x
• rclone binary - Installation Guide

⚙️ Configuration

The package automatically uses your existing config/filesystems.php configuration:

// config/filesystems.php
'disks' => [
 's3' => [
 'driver' => 's3',
 'key' => env('AWS_ACCESS_KEY_ID'),
 'secret' => env('AWS_SECRET_ACCESS_KEY'),
 'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
 'bucket' => env('AWS_BUCKET'),
 ],
 'sftp' => [
 'driver' => 'sftp',
 'host' => env('SFTP_HOST'),
 'username' => env('SFTP_USERNAME'),
 'password' => env('SFTP_PASSWORD'),
 'port' => env('SFTP_PORT', 22),
 ],
]

Optional: Publish config for advanced settings:

php artisan vendor:publish --provider="InnoGE\LaravelRclone\RcloneServiceProvider" --tag="rclone-config"

🎯 API Reference

Core Operations

// Sync (make target identical to source)
$result = Rclone::source('s3', 'data')->target('backup')->sync();

// Copy (don't delete from target)
$result = Rclone::source('s3', 'data')->target('backup')->copy();

// Move (delete from source after transfer)
$result = Rclone::source('s3', 'data')->target('backup')->move();

Performance Tuning

Rclone::source('s3', 'large-dataset')
 ->target('backup', 'archive')
 ->transfers(32) // Parallel transfers
 ->checkers(16) // File checkers
 ->retries(5) // Retry attempts
 ->statInterval(10) // Stats interval (seconds)
 ->option('bandwidth', '50M') // Custom rclone option
 ->sync();

Progress Monitoring

$result = Rclone::source('s3', 'files')
 ->target('local', 'backup')
 ->withProgress()
 ->getOutputUsing(function ($type, $output) {
 if ($type === 'out') {
 echo "Progress: {$output}";
 } else {
 Log::error("Rclone Error: {$output}");
 }
 })
 ->sync();

// Check results
if ($result->isSuccessful()) {
 $stats = $result->getStats();
 echo "Transferred: {$stats['transferred_files']} files\n";
 echo "Data: {$stats['transferred_bytes']} bytes\n";
} else {
 echo "Failed: {$result->getErrorOutput()}\n";
}

🔌 Supported Storage Providers

Provider	Driver	Required Config
Local Filesystem	local	root
Amazon S3	s3	key, secret, region, bucket
SFTP	sftp	host, username, password/key_file
FTP	ftp	host, username, password

S3 Configuration

's3' => [
 'driver' => 's3',
 'key' => 'AKIAIOSFODNN7EXAMPLE',
 'secret' => 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
 'region' => 'us-west-2',
 'bucket' => 'my-bucket',
 'endpoint' => 'https://s3.amazonaws.com', // Optional
 'use_path_style_endpoint' => false, // Optional
]

SFTP Authentication

'sftp' => [
 'driver' => 'sftp',
 'host' => 'server.example.com',
 'username' => 'user',
 // Password auth
 'password' => 'secret',
 // OR Key file auth
 'key_file' => '/path/to/private/key',
 // OR Inline key auth
 'private_key' => '-----BEGIN OPENSSH PRIVATE KEY-----...',
 'port' => 22,
]

🏗️ Laravel Integration

Dependency Injection

use InnoGE\LaravelRclone\Contracts\RcloneInterface;

class BackupService
{
 public function __construct(
 private RcloneInterface $rclone
 ) {}

 public function dailyBackup(): bool
 {
 $result = $this->rclone
 ->source('local', 'app/data')
 ->target('s3', 'backups/daily')
 ->withProgress()
 ->sync();

 return $result->isSuccessful();
 }
}

Artisan Command Example

use InnoGE\LaravelRclone\Facades\Rclone;

class BackupCommand extends Command
{
 public function handle(): int
 {
 $this->info('Starting backup...');

 $result = Rclone::source('local', 'storage/app')
 ->target('s3', 'backups/' . now()->format('Y-m-d'))
 ->withProgress()
 ->getOutputUsing(fn($type, $output) => $this->line($output))
 ->sync();

 return $result->isSuccessful() ? 0 : 1;
 }
}

🛠️ Advanced Configuration

Environment variables:

RCLONE_BINARY_PATH=/usr/local/bin/rclone
RCLONE_TIMEOUT=7200

Custom config file (config/rclone.php):

return [
 'binary_path' => env('RCLONE_BINARY_PATH', 'rclone'),
 'timeout' => env('RCLONE_TIMEOUT', 3600),
 'base_options' => [
 '--delete-after',
 '--fast-list',
 '--checksum',
 ],
 'defaults' => [
 'transfers' => 4,
 'checkers' => 8,
 'retries' => 3,
 'progress' => false,
 ],
];

🧪 Testing

# Run tests
composer test

# With coverage
composer test-coverage

# Static analysis
composer analyse

# Format code
composer format

🤝 Contributing

Contributions welcome! Please submit issues and pull requests on GitHub.

💝 Built With Love

This package was crafted with passion by amazing developers:

• Daniel Seuffer - Creator & Maintainer
• Tim Geisendoerfer - Inspiring Leader, Core Contributor
• All Contributors - Community Heroes ❤️

📄 License

MIT License. See LICENSE for details.

⚡ Powered by rclone - The Swiss Army knife of cloud storage