Flysystem SFTP Adapter (v3)

league/flysystem-sftp-v3 is the official SFTP adapter for Flysystem, The PHP League’s filesystem abstraction library. It lets your application read, write, list, and manage files on a remote server over SFTP using the same unified Flysystem API you would use for local disks, Amazon S3, or any other storage backend.

Built on phpseclib v3 for the underlying SSH/SFTP transport, the adapter supports password and private-key authentication, configurable host-key verification, custom ports and timeouts, and permission mapping. Because it plugs into Flysystem, swapping remote SFTP storage in or out of an application is a matter of changing which adapter you instantiate, with no changes to your file-handling code.

What You Get

• A Flysystem-compatible SftpAdapter for reading and writing files over SFTP
• Password and private-key (with optional passphrase) authentication
• Configurable host-key verification via connectivity checkers
• Custom port, timeout, root path, and permission settings
• Typed exceptions for connection, authentication, and host-authenticity failures

Common Use Cases

• Reading and writing files on a remote server without SFTP-specific glue code
• Swapping between local, S3, and SFTP storage behind a single Flysystem interface
• Transferring generated exports, backups, or uploads to a partner’s SFTP server

Under The Hood

Architecture

The adapter centers on SftpAdapter, which implements Flysystem’s FilesystemAdapter interface and translates Flysystem operations (write, read, listContents, delete, setVisibility, etc.) into phpseclib SFTP calls. Connections are decoupled behind a ConnectionProvider contract, with SftpConnectionProvider building and caching an authenticated phpseclib SFTP client from host/credentials/options. Host-key trust is handled by a ConnectivityChecker abstraction (SimpleConnectivityChecker, FixatedConnectivityChecker). Failure modes are surfaced as dedicated exception classes (UnableToConnectToSftpHost, UnableToAuthenticate, UnableToLoadPrivateKey, UnableToEstablishAuthenticityOfHost).

Tech Stack

PHP 8.0.2+, depending on league/flysystem ^3, league/mime-type-detection, and phpseclib/phpseclib ^3 for the pure-PHP SSH/SFTP implementation. It autoloads via PSR-4 under League\Flysystem\PhpseclibV3. It is distributed as a sub-split of the main thephpleague/flysystem monorepo.

Code Quality

The code is small, focused, and strongly typed, with clear separation between the adapter, connection provisioning, and connectivity checking. It ships PHPUnit tests (SftpAdapterTest, SftpConnectionProviderTest) plus stubs for deterministic testing, and inherits the mature review and CI practices of The PHP League.

API Design

Usage follows the established Flysystem pattern: construct a connection provider, wrap it in the adapter, and pass it to a Filesystem. The configuration surface is well-named and documented on the Flysystem site, so anyone familiar with Flysystem can adopt it with minimal effort.