PHPackages                             verseles/flyclone - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [File & Storage](/categories/file-storage)
4. /
5. verseles/flyclone

ActiveLibrary[File & Storage](/categories/file-storage)

verseles/flyclone
=================

PHP wrapper for rclone

v4.0.1(3mo ago)91.9k↓44.4%CC-BY-NC-SA-4.0PHPPHP >=8.4CI failing

Since Mar 12Pushed 1mo agoCompare

[ Source](https://github.com/verseles/flyclone)[ Packagist](https://packagist.org/packages/verseles/flyclone)[ RSS](/packages/verseles-flyclone/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (6)Versions (54)Used By (0)

Verseles\\Flyclone
==================

[](#verselesflyclone)

PHP wrapper for [rclone](https://rclone.org/) - the Swiss army knife of cloud storage.

[![PHPUnit](https://camo.githubusercontent.com/91a3a4e364b341ceb26bc18ebf4332fbc1d86150ebdf2f0221637a703903543e/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f76657273656c65732f666c79636c6f6e652f706870756e69742e796d6c3f7374796c653d666f722d7468652d6261646765266c6162656c3d504850556e6974)](https://github.com/verseles/flyclone/actions)[![PHP](https://camo.githubusercontent.com/d9a2ccc2235ef3e1cf92c8caffb0efd0aabce5ec07c18abe94dd9fff58d99f43/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e342b2d3737376262343f7374796c653d666f722d7468652d6261646765266c6f676f3d706870266c6f676f436f6c6f723d7768697465)](https://www.php.net/)[![License](https://camo.githubusercontent.com/3b36213e329d3585b74d2dd2e7e41940fe9e732bb051f531cadbf08f517ddb12/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d43432d2d42592d2d4e432d2d53412d2d342e302d677265656e3f7374796c653d666f722d7468652d6261646765)](LICENSE.md)

Flyclone provides an intuitive, object-oriented interface for interacting with rclone. Transfer files between 70+ cloud providers with progress tracking, detailed statistics, and robust error handling.

Features
--------

[](#features)

- **70+ Storage Backends** - Local, S3, SFTP, FTP, Dropbox, Google Drive, Mega, B2, and more
- **Fluent API** - Clean, chainable interface for all rclone operations
- **Progress Tracking** - Real-time transfer progress with speed, ETA, and percentage
- **Transfer Statistics** - Detailed stats (bytes, files, speed, errors) after each operation
- **Encryption Support** - Transparent encryption via CryptProvider
- **Union Filesystems** - Merge multiple providers into a single virtual filesystem
- **Type-Safe Errors** - Specific exceptions for each rclone exit code
- **Automatic Retry** - Exponential backoff for transient failures
- **Filtering API** - Fluent builder for include/exclude patterns
- **Security First** - Secrets redaction in errors, credential validation warnings
- **Debug Mode** - Command introspection and structured logging

Requirements
------------

[](#requirements)

- PHP >= 8.4
- [rclone](https://rclone.org/install/) binary in PATH

Installation
------------

[](#installation)

```
composer require verseles/flyclone
```

Quick Start
-----------

[](#quick-start)

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

// Single provider - operations on one remote
$local = new LocalProvider('myDisk');
$rclone = new Rclone($local);
$files = $rclone->ls('/path/to/files');

// Two providers - transfer between remotes
$s3 = new S3Provider('myS3', [
    'access_key_id' => 'YOUR_KEY',
    'secret_access_key' => 'YOUR_SECRET',
    'region' => 'us-east-1',
]);
$rclone = new Rclone($local, $s3);
$result = $rclone->copy('/local/data', 'my-bucket/backup');

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

Supported Providers
-------------------

[](#supported-providers)

ProviderClassNotesLocal filesystem`LocalProvider`Amazon S3 / MinIO`S3Provider`S3-compatibleSFTP`SFtpProvider`SSH File TransferFTP`FtpProvider`Dropbox`DropboxProvider`Google Drive`GDriveProvider`Mega.nz`MegaProvider`Backblaze B2`B2Provider`**Encryption**`CryptProvider`Wraps any provider**Union**`UnionProvider`Merges multiple providers> All [70+ rclone backends](https://rclone.org/overview/) can be used via the generic `Provider` class.

Advanced Features
-----------------

[](#advanced-features)

### Encryption with CryptProvider

[](#encryption-with-cryptprovider)

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

$s3 = new S3Provider('myS3', [/* config */]);
$encrypted = new CryptProvider('encrypted', [
    'password' => Rclone::obscure('my-secret-password'),
    'password2' => Rclone::obscure('my-salt'),
], $s3);

$rclone = new Rclone($encrypted);
$rclone->copy('/local/sensitive-data', '/encrypted-bucket/backup');
// Files are transparently encrypted before upload
```

### Union Filesystem

[](#union-filesystem)

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

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

$union = new UnionProvider('combined', [
    'action_policy' => 'all',
    'create_policy' => 'ff',
], [$local, $s3]);

$rclone = new Rclone($union);
$files = $rclone->ls('/'); // Lists files from both local and S3
```

### Global Configuration

[](#global-configuration)

```
// Set rclone binary path (auto-detected by default)
Rclone::setBIN('/custom/path/to/rclone');

// Set global flags for all operations
Rclone::setFlags(['checksum' => true, 'verbose' => true]);

// Set environment variables
Rclone::setEnvs(['RCLONE_BUFFER_SIZE' => '64M']);

// Set timeouts
Rclone::setTimeout(300);     // Max execution time (seconds)
Rclone::setIdleTimeout(120); // Idle timeout (seconds)

// Obscure passwords
$obscured = Rclone::obscure('plain-password');
```

### Error Handling

[](#error-handling)

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

try {
    $rclone->copy($source, $dest);
} catch (FileNotFoundException $e) {
    // File doesn't exist - no retry needed
} catch (DirectoryNotFoundException $e) {
    // Directory doesn't exist
} catch (TemporaryErrorException $e) {
    // Temporary error - retry may succeed
    if ($e->isRetryable()) {
        // Can check programmatically
    }
    // Rich context available
    $context = $e->getContext(); // ['command' => '...', 'provider' => '...']
}
```

### Automatic Retry

[](#automatic-retry)

```
use Verseles\Flyclone\RetryHandler;

// Simple retry configuration
$rclone->retry(maxAttempts: 5, baseDelayMs: 1000)
    ->copy($source, $dest);

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

$rclone->withRetry($handler)->copy($source, $dest);
```

### Filtering

[](#filtering)

```
use Verseles\Flyclone\FilterBuilder;

// Filter by extension and size
$rclone->withFilter(
    FilterBuilder::create()
        ->extensions(['jpg', 'png', 'gif'])
        ->minSize('100K')
        ->maxSize('50M')
        ->exclude('**/thumbnails/**')
)->copy($source, $dest);

// Filter by age
$rclone->withFilter(
    FilterBuilder::create()
        ->newerThan('7d')  // Last 7 days
        ->include('*.log')
)->sync($source, $dest);
```

### Dry-Run Mode

[](#dry-run-mode)

```
// Preview what would happen without making changes
$rclone->dryRun(true)->sync($source, $dest);

// Check if dry-run is enabled
if ($rclone->isDryRun()) {
    echo "Running in simulation mode";
}
```

### Health Check

[](#health-check)

```
// Verify provider connectivity
$health = $rclone->healthCheck();

if ($health->healthy) {
    echo "Connected in {$health->latency_ms}ms";
} else {
    echo "Failed: {$health->error}";
}
```

### Debugging

[](#debugging)

```
use Verseles\Flyclone\Logger;

// Enable debug mode to log all commands
Logger::setDebugMode(true);

// After an operation, inspect what was executed
$rclone->copy($source, $dest);
echo $rclone->getLastCommand();  // "rclone copy ..."

// Get redacted environment variables
$envs = $rclone->getLastEnvs();  // Secrets are [REDACTED]

// Retrieve all debug logs
$logs = Logger::getLogs();
```

Testing
-------

[](#testing)

```
# Install dependencies
composer install

# Run quick tests (local provider only)
make test

# Run full offline test suite (requires podman-compose)
make test-offline

# Run specific provider tests (requires .env configuration)
make test_dropbox
make test_gdrive
```

Architecture
------------

[](#architecture)

Flyclone v4 uses a modular architecture:

ComponentResponsibility`Rclone`Main orchestrator, public API`ProcessManager`Process execution, binary detection, error mapping`CommandBuilder`Command construction, environment variables`StatsParser`Transfer statistics parsing`ProgressParser`Real-time progress parsing`RetryHandler`Exponential backoff retry mechanism`FilterBuilder`Fluent API for include/exclude patterns`SecretsRedactor`Sensitive data redaction in errors/logs`Logger`Structured logging with debug modeContributing
------------

[](#contributing)

1. Fork the repository
2. Create a feature branch
3. Write tests for new functionality
4. Ensure all tests pass: `make test-offline`
5. Submit a pull request

Changelog
---------

[](#changelog)

### v4.0.0 (In Development)

[](#v400-in-development)

**Feature 1: Core Refactoring (alpha)**

- Extracted `ProcessManager`, `CommandBuilder`, `StatsParser`, `ProgressParser` from monolithic `Rclone` class
- Fixed `CryptProvider` and `UnionProvider` - now fully functional
- Added `ConfigurationTest` (13 tests) and `EdgeCasesTest` (13 tests)
- Migrated to `podman-compose`

**Feature 2: Security & DX (beta)**

- Added `SecretsRedactor` - automatic redaction of sensitive data in errors
- Added `RetryHandler` - exponential backoff for transient failures
- Added `FilterBuilder` - fluent API for include/exclude patterns
- Added `Logger` - structured logging with debug mode
- Added `healthCheck()` - provider connectivity verification
- Added `dryRun()` - simulation mode for operations
- Added command introspection (`getLastCommand()`, `getLastEnvs()`)
- Added exception context (`isRetryable()`, `getContext()`)
- Added credential validation warnings for plaintext passwords
- Added `Feature2Test` (28 tests), 125+ tests total

**Feature 3: Polish & Release (rc)**

- Integrated PHPStan (level 5) and Laravel Pint (PSR-12) with CI
- Added new commands: `bisync()`, `md5sum()`, `sha1sum()`
- Added static utilities: `listRemotes()`, `configFile()`, `configDump()`
- Formatted entire codebase with `declare(strict_types=1)`
- All tests passing (150+ tests)

### v3.x

[](#v3x)

- Transfer operations return detailed statistics object
- Progress tracking improvements

License
-------

[](#license)

[Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International](LICENSE.md)

###  Health Score

56

—

FairBetter than 98% of packages

Maintenance86

Actively maintained with recent releases

Popularity26

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity84

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 97.6% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~44 days

Recently: every ~54 days

Total

42

Last Release

98d ago

Major Versions

v0.21 → v1.0.12023-12-01

v1.1.2 → v2.0.02024-05-20

v2.5.0 → v3.0.02025-07-07

v3.0.1 → v4.x-dev2026-01-04

PHP version history (3 changes)0.8PHP >=7.4

v0.17PHP >=8.0

v2.2.0PHP >=8.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/934b53b68624e78343e3f3367897cbaf5fb01475511a1650d2c99c972c810ec6?d=identicon)[insign](/maintainers/insign)

---

Top Contributors

[![insign](https://avatars.githubusercontent.com/u/1113045?v=4)](https://github.com/insign "insign (165 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (2 commits)")[![google-labs-jules[bot]](https://avatars.githubusercontent.com/in/842251?v=4)](https://github.com/google-labs-jules[bot] "google-labs-jules[bot] (1 commits)")[![jaytagdamian](https://avatars.githubusercontent.com/u/17107538?v=4)](https://github.com/jaytagdamian "jaytagdamian (1 commits)")

---

Tags

cloudatlasdiskdropboxflysystemhacktoberfestphpphp-wrapperrclonewrapperftpfilesystemabstractions3awscloudsftpfilesstorageWebDAVfilesystemsremotesyncdropboxrackspacercloneCloud Filesfile systems

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/verseles-flyclone/health.svg)

```
[![Health](https://phpackages.com/badges/verseles-flyclone/health.svg)](https://phpackages.com/packages/verseles-flyclone)
```

###  Alternatives

[league/flysystem

File storage abstraction for PHP

13.6k639.1M2.2k](/packages/league-flysystem)[creocoder/yii2-flysystem

The flysystem extension for the Yii framework

2931.7M62](/packages/creocoder-yii2-flysystem)[innoge/laravel-rclone

A sleek PHP wrapper around rclone with Laravel-style fluent API syntax

174.1k](/packages/innoge-laravel-rclone)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)