Flysystem Ftp Laravel Package

Getting Started

Install the package via Composer and ensure the ext-ftp PHP extension is enabled (common on most Linux hosts, but not always enabled by default on Windows or minimal Docker images):

composer require league/flysystem-ftp

Begin by instantiating the FtpAdapter with connection options (host, username, password, and optionally port, timeout, and passive mode). Use Laravel’s filesystem abstraction if working in a Laravel app: define a new ftp disk in config/filesystems.php using league/flysystem-ftp under the hood. A minimal working example in plain PHP:

use League\Flysystem\FTP\FtpAdapter;
use League\Flysystem\Filesystem;

$adapter = new FtpAdapter([
    'host'     => 'ftp.example.com',
    'username' => 'user',
    'password' => 'pass',
    'port'     => 21,
    'timeout'  => 30,
    'useSSL'   => false,
    'passive'  => true,
]);

$filesystem = new Filesystem($adapter);
$filesystem->write('hello.txt', 'Hello, FTP!');

First practical use case: upload local files (e.g., logs, reports) to a remote backup server.

Implementation Patterns

• Laravel Integration: Use the built-in ftp disk support. Set DISK_FTP_* environment variables and configure config/filesystems.php with 'driver' => 'ftp'. Add FTP_HOST, FTP_USERNAME, etc., to .env. Laravel automatically uses this adapter when resolving Storage::disk('ftp').
• Conditional Failover: Wrap FTP operations in retry logic or fallback to S3 when FTP is unavailable (e.g., via try/catch on ConnectionFailedException).
• Batch Operations: Leverage Flysystem’s listContents() and copy()/move() methods to mirror local directories to FTP with filtering.
• Static Files CDN: Use FTP to sync compiled public assets (CSS, JS, images) to legacy shared hosting where only FTP is supported.
• Testing: Inject the FilesystemInterface instead of concrete adapter for easy mocking in unit tests.

Integrate with Laravel Queue Jobs to offload large uploads asynchronously.

Gotchas and Tips

• Passive Mode: Often required with firewalls/NAT; default is true, but double-check server requirements. passive must be true for most modern FTP servers behind NAT.
• SSL/TLS Support: The adapter does not support FTPS (FTP over SSL) — use league/flysystem-async-ftp or league/flysystem-sftp for secure variants.
• Long-Running Transfers: FTP connections may time out during large uploads; set timeout and consider resuming uploads (Flysystem doesn’t support resume natively — implement chunking manually if needed).
• Path Handling: Avoid hardcoded / vs \ issues — use Flysystem’s unified paths (no trailing slashes on directories in write()/read()).
• Error Types: Watch for ConnectionFailedException, FilesystemException, and UnableToWriteFile. UnableToWriteFile often hides network flakiness — retry with backoff.
• Credentials in Config: In Laravel, avoid storing FTP passwords in version control — use encrypted env or vault-based secrets.
• MIME Type Detection: This adapter depends on league/mime-type-detection; ensure no other adapters conflict with MIME inference (especially when using mimeType() or automatic detection on upload).
• Debugging: Enable FTP logging by wrapping the adapter in a LoggingAdapter, or set FTP_DEBUG=1 in your shell to see raw protocol output if using PHP’s ftp_* functions directly in debugging code.