Download the PHP package verseles/flyclone without Composer

Verseles\Flyclone

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

Quick Start

For one-remote operations, pass only one provider:

Providers

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

Upload and download helpers create unique temporary local remotes internally:

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.

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.

Union Filesystems

UnionProvider receives upstream providers through upstream_providers.

Configuration

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

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

Filtering

Progress, Retry, And Dry Run

Error Handling

Debugging

Utilities

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

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

Architecture

Flyclone v5 is organized around small components:

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