Flysystem

Flysystem is a filesystem abstraction library for PHP that gives applications a single, consistent API for reading, writing, and listing files regardless of where they’re actually stored. The same Filesystem object and method calls (write, read, delete, listContents, fileExists) work whether the underlying storage is the local disk, AWS S3, Google Cloud Storage, an FTP/SFTP server, WebDAV, MongoDB GridFS, or an in-memory adapter for tests — swapping storage backends means swapping an adapter, not rewriting application code.

This single monorepo houses the core Filesystem/adapter contracts plus most first-party adapters as sub-packages (league/flysystem-aws-s3-v3, league/flysystem-ftp, league/flysystem-sftp-v3, and others), each independently installable via Composer while sharing the same core interfaces and test suite utilities. It’s the storage layer underneath Laravel’s Storage facade and widely used across the PHP ecosystem for vendor-neutral file handling.

What You Get

• A core Filesystem class implementing write, read, delete, copy, move, listContents, fileExists, and visibility/metadata operations against any adapter
• First-party adapters for Local disk, FTP, SFTP, AWS S3, AsyncAws S3, Google Cloud Storage, MongoDB GridFS, WebDAV, Azure Blob Storage, and ZipArchive, each as its own installable sub-package
• An InMemory adapter for fast, isolated filesystem tests without touching real storage
• A MountManager for working across multiple configured filesystems (e.g. copying between S3 and local disk) through one interface
• AdapterTestUtilities — a shared compliance test suite any custom adapter can run against to verify correct behavior
• A stable FilesystemException/UnableTo* exception hierarchy giving specific, catchable failure reasons for every operation

Common Use Cases

• Storing user file uploads without hardcoding a specific cloud provider’s SDK throughout the application
• Switching a production application from local disk storage to S3 (or another provider) by changing configuration, not application code
• Building a custom storage adapter for a niche backend using the shared AdapterTestUtilities compliance tests
• Powering Laravel’s Storage facade, which uses Flysystem adapters under the hood for all its disk drivers
• Testing file-handling code quickly and deterministically using the InMemory adapter instead of real network storage

Under The Hood

Architecture: src/Filesystem.php implements FilesystemOperator/FilesystemReader/FilesystemWriter, delegating every operation to an injected FilesystemAdapter implementation; each backend (Local/, Ftp/, AwsS3V3/, GoogleCloudStorage/, WebDAV/, GridFS/, ZipArchive/, etc.) implements that same adapter contract against its native client library. MountManager.php composes multiple named filesystems behind one facade for cross-filesystem operations, and PathNormalizer/PathPrefixer centralize path-safety handling (rejecting path traversal, normalizing separators) so every adapter benefits from the same hardening.

Tech Stack: PHP 8.0.2+, structured as a single Composer monorepo where each adapter is both a subdirectory of src/ and an independently Composer-installable sub-split package (e.g. league/flysystem-aws-s3-v3 depends on the AWS SDK, league/flysystem-sftp-v3 on phpseclib). PHPUnit for testing and PHPStan (level 6) for static analysis.

Code Quality: The repo contains 35+ dedicated test files at the top level alone (plus per-adapter suites), and every adapter runs the same shared AdapterTestUtilities compliance tests, ensuring behavioral parity across radically different storage backends. Failure modes are modeled as specific typed exceptions (UnableToWriteFile, UnableToCheckFileExistence, etc.) rather than generic errors, giving callers precise, catchable failure information.

API Design: The entire library is built around one small, deliberately storage-agnostic interface — the same five or six method calls work identically against local disk, S3, or an in-memory test double — which is the core value proposition: application code never branches on which storage backend is active.