README

PHP 8.4+ wrapper for rclone, focused on safe, testable file operations across local disks, S3-compatible storage, SFTP, FTP, Google Drive, Dropbox, Mega, B2, and the rest of rclone's backends.

Why Flyclone

Object-oriented providers around rclone remotes.
Single-remote and two-remote operations through the same Rclone class.
Transfer statistics and optional progress callbacks.
Typed exceptions for rclone exit codes.
Retry support with exponential backoff.
Fluent include/exclude filters.
Debug logging with secret redaction.
v5 safety hardening for long-lived workers: instance-scoped options, provider collision detection, safe temporary remotes, private temp directories, and inline SFTP key support.

Requirements

PHP >= 8.4
ext-json
rclone binary available in PATH, or configured with Rclone::setBIN()

Installation

composer require verseles/flyclone:^5.0

Quick Start

use Verseles\Flyclone\Providers\LocalProvider;
use Verseles\Flyclone\Providers\S3Provider;
use Verseles\Flyclone\Rclone;

$local = new LocalProvider('local_disk');

$s3 = new S3Provider('archive_bucket', [
    'access_key_id' => 'YOUR_KEY',
    'secret_access_key' => 'YOUR_SECRET',
    'region' => 'us-east-1',
]);

$rclone = new Rclone($local, $s3);
$result = $rclone->copy('/var/backups', 'my-bucket/backups');

if ($result->success) {
    echo "Transferred {$result->stats->bytes} bytes at {$result->stats->speed_human}";
}

For one-remote operations, pass only one provider:

$files = (new Rclone($local))->ls('/var/backups');

Providers

Backend	Class	Notes
Local filesystem	`LocalProvider`	Local paths and temporary helper remotes
Amazon S3 / MinIO / R2	`S3Provider`	S3-compatible flags map to rclone env config
SFTP	`SFtpProvider`	Supports password, `key_file`, and v5 inline `key_pem`/`private_key`
FTP	`FtpProvider`	FTP/FTPS
Google Drive	`GDriveProvider`	OAuth/config-driven rclone backend
Dropbox	`DropboxProvider`	OAuth/config-driven rclone backend
Mega.nz	`MegaProvider`	Mega backend
Backblaze B2	`B2Provider`	B2 backend
Encrypted remote	`CryptProvider`	Wraps another provider
Union filesystem	`UnionProvider`	Merges upstream providers
Any other rclone backend	`Provider`	Generic provider class

Provider names are normalized to rclone-safe uppercase remote names. In v5, names that normalize to an empty value are rejected, and conflicting provider environment variables fail fast instead of being silently overwritten.

Core Operations

$rclone = new Rclone($sourceProvider, $destProvider);

$rclone->copy('/source/dir', '/dest/dir');
$rclone->copyto('/source/file.txt', '/dest/file.txt');
$rclone->move('/source/dir', '/dest/dir');
$rclone->moveto('/source/file.txt', '/dest/file.txt');
$rclone->sync('/source/dir', '/dest/dir');
$rclone->delete('/path/to/delete');

Upload and download helpers create unique temporary local remotes internally:

$rclone = new Rclone($s3);

$rclone->upload_file('/tmp/report.pdf', 'bucket/reports/report.pdf');
$download = $rclone->download_to_local('bucket/reports/report.pdf');

echo $download->local_path;

SFTP Private Keys

Prefer inline PEM keys in v5. Flyclone passes the value to rclone as RCLONE_CONFIG_<REMOTE>_KEY_PEM; no key file is created by Flyclone.

use Verseles\Flyclone\Providers\SFtpProvider;

$sftp = new SFtpProvider('deploy', [
    'host' => 'sftp.example.com',
    'user' => 'deploy',
    'private_key' => $privateKeyPem,
    'key_use_agent' => false,
]);

private_key is a convenience alias for key_pem. key_pem and key_file are mutually exclusive.

Encryption

CryptProvider wraps another provider through the required remote flag.

use Verseles\Flyclone\Providers\CryptProvider;
use Verseles\Flyclone\Providers\S3Provider;
use Verseles\Flyclone\Rclone;

$s3 = new S3Provider('raw_archive', [
    'access_key_id' => 'YOUR_KEY',
    'secret_access_key' => 'YOUR_SECRET',
    'region' => 'us-east-1',
]);

$encrypted = new CryptProvider('encrypted_archive', [
    'remote' => $s3,
    'remote_path' => 'encrypted-prefix',
    'password' => Rclone::obscure('my-secret-password'),
    'password2' => Rclone::obscure('my-salt'),
]);

(new Rclone($encrypted))->copy('/local/sensitive-data', '/');

Union Filesystems

UnionProvider receives upstream providers through upstream_providers.

use Verseles\Flyclone\Providers\LocalProvider;
use Verseles\Flyclone\Providers\S3Provider;
use Verseles\Flyclone\Providers\UnionProvider;
use Verseles\Flyclone\Rclone;

$cache = new LocalProvider('cache', ['root' => '/tmp/cache']);
$archive = new S3Provider('archive', [/* config */]);

$union = new UnionProvider('combined', [
    'upstream_providers' => [$cache, $archive],
    'action_policy' => 'all',
    'create_policy' => 'ff',
]);

$files = (new Rclone($union))->ls('/');

Configuration

Static configuration is still available and is captured by new Rclone instances at construction time:

Rclone::setBIN('/custom/path/to/rclone');
Rclone::setFlags(['checksum' => true]);
Rclone::setEnvs(['RCLONE_BUFFER_SIZE' => '64M']);
Rclone::setTimeout(300);
Rclone::setIdleTimeout(120);

For long-lived workers, prefer instance-scoped options:

$rclone = (new Rclone($source, $dest))
    ->withFlags(['checksum' => true])
    ->withEnvs(['RCLONE_BUFFER_SIZE' => '64M'])
    ->withTimeout(300)
    ->withIdleTimeout(120);

Filtering

use Verseles\Flyclone\FilterBuilder;

$filter = FilterBuilder::create()
    ->extensions(['jpg', 'png', 'gif'])
    ->minSize('100K')
    ->maxSize('50M')
    ->exclude('**/thumbnails/**');

$rclone->withFilter($filter)->copy('/source', '/dest');

Progress, Retry, And Dry Run

use Verseles\Flyclone\RetryHandler;

$handler = RetryHandler::create()
    ->maxAttempts(5)
    ->baseDelay(500)
    ->multiplier(2.0)
    ->maxDelay(30000)
    ->onRetry(fn (int $attempt, Throwable $e) => logger("Retry {$attempt}: {$e->getMessage()}"));

$progress = function (object $progress): void {
    echo $progress->percentage . "%\n";
};

$rclone->withRetry($handler)
    ->dryRun(false)
    ->copy('/source', '/dest', onProgress: $progress);

Error Handling

use Verseles\Flyclone\Exception\DirectoryNotFoundException;
use Verseles\Flyclone\Exception\FileNotFoundException;
use Verseles\Flyclone\Exception\TemporaryErrorException;

try {
    $rclone->copy('/source', '/dest');
} catch (FileNotFoundException|DirectoryNotFoundException $e) {
    // Permanent user/input error.
} catch (TemporaryErrorException $e) {
    if ($e->isRetryable()) {
        // Retry may succeed.
    }

    $context = $e->getContext();
}

Debugging

use Verseles\Flyclone\Logger;

Logger::setDebugMode(true);

$rclone->copy('/source', '/dest');

echo $rclone->getLastCommand();
$envs = $rclone->getLastEnvs(); // Secrets are redacted.
$logs = Logger::getLogs();

Utilities

$remotes = Rclone::listRemotes();
$config = Rclone::configDump();
$md5 = $rclone->md5sum('/path');
$sha1 = $rclone->sha1sum('/path');
$health = $rclone->healthCheck('/');

v5 Breaking Changes

Provider names that normalize to an empty rclone remote name now throw InvalidArgumentException.
Conflicting provider env vars now throw LogicException instead of overwriting values.
Two providers with the same normalized remote name and different config now fail fast.
Existing Rclone instances no longer observe later changes to static flags/envs/timeouts; use withFlags(), withEnvs(), withTimeout(), and withIdleTimeout() for per-instance updates.
SFtpProvider rejects ambiguous key_pem plus key_file configuration.

See MIGRATION.md for migration notes.

Testing

composer install

# Fast local/offline checks
composer test-local
make test

# Full offline provider suite, when podman-compose is available
make test-offline

# Static analysis and formatting
composer analyse
composer run-script format-check

Provider-specific tests such as make test_dropbox and make test_gdrive require a configured .env.

Architecture

Flyclone v5 is organized around small components:

Component	Responsibility
`Rclone`	Public API and operation orchestration
`Provider` and subclasses	rclone remote configuration
`CommandBuilder`	Command arguments and environment variables
`ProcessManager`	Symfony Process execution and binary detection
`StatsParser`	Transfer statistics parsing
`ProgressParser`	Real-time progress parsing
`RetryHandler`	Retry policy and backoff
`FilterBuilder`	Include/exclude filter construction
`TemporaryPath`	Private temp directories and unique temporary remote names
`SecretsRedactor`	Secret redaction for errors/logs/envs
`Logger`	Structured debug logging

Changelog

v5.0.0

Hardened provider configuration for long-lived workers.
Added instance-scoped flags, envs, and timeouts.
Added provider env collision detection.
Added remote-name collision detection.
Added safe temporary local provider names.
Added private temporary download directories.
Added SFTP inline private key support via key_pem/private_key.
Added configuration/security tests to the fast test path.

v4.x

Modularized Rclone internals into process, command, stats, progress, retry, filter, logger, and redaction components.
Added typed exception context, health checks, dry-run mode, command introspection, and static utilities.
Added CryptProvider and UnionProvider support.

v3.x

Added detailed transfer statistics and progress tracking improvements.

License

Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International

verseles / flyclone

Maintainers

Package info

Statistics

Security