thephpleague/flysystem

This system is a modular filesystem abstraction library that provides a unified interface for interacting with diverse storage backends. It supports a wide range of adapters, including local disk, cloud services like AWS S3 and Azure Blob, and network protocols such as FTP, SFTP, and WebDAV. The architecture allows for granular dependency management through sub-packages and includes utilities for URL generation, visibility handling, and comprehensive adapter testing.

16 changes.

The project underwent a major architectural shift to a monorepo structure, splitting the core library and individual adapters into separate sub-packages to allow modular installation. This period established the foundational Flysystem 3.0 API with new interfaces and attributes while introducing a suite of new adapters for AWS S3, Google Cloud, and in-memory storage. Concurrently, existing adapters were updated or deprecated, and comprehensive testing infrastructure was built to support the new sub-split publishing model.

7 changes.

This period focused on expanding Flysystem's ecosystem by introducing new storage adapters for SFTP, Azure Blob Storage, and GridFS, alongside a read-only wrapper. It also established a standardized URL generation framework with public and temporary URL interfaces, enhancing path prefixing capabilities to support these new features.

Added the entry point (server.php) and configuration (.gitignore) for the new WebDAV adapter. The server initializes a SabreDAV instance pointing to a local 'data' directory, includes the SabreDAV browser plugin for UI access, and configures a content-type guesser to correctly map .svg files to image/svg+xml while suppressing PHP deprecation warnings.

src/WebDAV/resources · high confidence

Introduces the new AwsS3V3 adapter for Flysystem, providing a modern implementation for AWS S3 storage. The adapter implements the standard FilesystemAdapter interface along with PublicUrlGenerator, TemporaryUrlGenerator, and ChecksumProvider capabilities. It supports configurable options for ACLs, SSE-C encryption, and multipart uploads, and includes a PortableVisibilityConverter to handle public/private visibility mappings. The release also includes a test stub for the S3 client to facilitate unit testing.

src/AwsS3V3, src/WebDAV · high confidence

This change introduces the new AzureBlobStorageAdapter, enabling users to store and retrieve files in Azure Blob Storage using the Flysystem interface. The adapter implements core filesystem operations (read, write, copy, move, delete) and supports public URL generation, temporary URL generation, and checksum calculation. It also provides configurable visibility handling to accommodate Azure's lack of native visibility support, allowing users to either throw errors or ignore visibility settings.

src/AzureBlobStorage · high confidence

The new Google Cloud Storage adapter now generates public URLs for objects and supports temporary URLs, allowing users to create time-limited access links. It also provides a uniform bucket-level access visibility handler to manage permissions in buckets where traditional ACLs are disabled, and includes automatic MIME type detection during uploads.

src/GoogleCloudStorage · high confidence

Users can now store files in MongoDB using the GridFS adapter by installing the \league/flysystem-gridfs\ package. This new adapter implements the Flysystem filesystem interface, allowing standard file operations (read, write, delete, list) to be performed against a MongoDB GridFS bucket. It supports file visibility and MIME type detection, handles directory simulation via metadata, and includes a test suite to verify compatibility with Flysystem's standard adapter contract.

src/GridFS · high confidence

This location introduces a new SFTP adapter implementation for Flysystem that uses the phpseclib v3 library instead of the previous version. The adapter provides full filesystem operations (read, write, copy, move, delete, directory management) and supports multiple authentication methods including password, private key, and SSH agent. It includes configurable host fingerprint verification (supporting multiple fingerprints and various hash formats), connection retry mechanisms, and optional ping-based connectivity checks. The implementation also adds support for PuTTY ppk files, configurable preferred algorithms, and stat cache disabling.

src/PhpseclibV3 · high confidence

The ZipArchive adapter is now available as a standalone sub-split within the Flysystem ecosystem. This change introduces the \ZipArchiveAdapter\ implementation along with its supporting infrastructure, including the \ZipArchiveProvider\ interface, \FilesystemZipArchiveProvider\ for managing archive creation and parent directory handling, and \StubZipArchive\ for testing. The adapter implements the standard \FilesystemAdapter\ contract, supporting file operations like read, write, delete, and directory management within ZIP archives, while also including specific exception classes for errors such as unable to create parent directories or open archives. Test coverage is provided through dedicated test cases like \ZipArchiveAdapterTestCase\ and specific root prefix tests.

src/ZipArchive · high confidence

Adds a new \InMemoryFilesystemAdapter\ that stores files in RAM, enabling fast, stateless file operations without disk I/O. The adapter supports standard operations including reading, writing, deleting, and listing contents, while also handling visibility settings and MIME type detection. A \StaticInMemoryAdapterRegistry\ is provided to manage named, persistent in-memory filesystem instances, allowing multiple isolated storage contexts within a single process. This is primarily useful for testing and scenarios where temporary, high-speed storage is required.

src/InMemory · high confidence

This change establishes the foundational API for the filesystem abstraction by introducing the \FilesystemAdapter\, \FilesystemReader\, and \FilesystemWriter\ interfaces, which define the contract for storage operations. It adds \FileAttributes\ and \DirectoryAttributes\ classes to represent file and directory metadata (such as path, visibility, size, and MIME type) with support for array access and JSON serialization. The update also includes a \MountManager\ for managing multiple filesystem mounts, a \DirectoryListing\ class for filtering and mapping directory contents, and a \DecoratedAdapter\ base class to simplify adapter implementation. Additionally, new exception classes like \FilesystemException\ and \CorruptedPathDetected\ are introduced to handle errors uniformly, and a \CalculateChecksumFromStream\ trait is added to support checksum generation.

src · high confidence

The local filesystem adapter is now available as a standalone package (league/flysystem-local). This update introduces lazy root directory creation, allowing the adapter to initialize without immediately creating the root folder, and adds a configurable fallback mechanism for MIME type detection that can resolve inconclusive results (like empty files) by falling back to extension-based lookup. The adapter also now implements checksum support and includes updated test coverage for these behaviors.

src/Local · high confidence

A new \league/flysystem-adapter-test-utilities\ package has been introduced to help developers test their custom filesystem adapters. It includes a \FilesystemAdapterTestCase\ base class that provides a comprehensive suite of contract tests for standard operations (read, write, delete, move, copy, etc.), along with utilities for handling retries on transient failures (via the \RetryOnTestException\ trait) and simulating network issues (via \ToxiproxyManagement\). The package also provides an \ExceptionThrowingFilesystemAdapter\ decorator to stage specific exceptions for error-handling tests and helper functions for mocking and stream management.

src/AdapterTestUtilities · high confidence

This release introduces a new \AsyncAwsS3Adapter\ that integrates the \async-aws/aws\ SDK into Flysystem, providing an asynchronous alternative to the existing synchronous AWS S3 adapters. The adapter implements the standard \FilesystemAdapter\ interface along with \PublicUrlGenerator\ and \TemporaryUrlGenerator\, enabling users to generate public and temporary URLs. It supports configurable forwarded options (such as ACL, CacheControl, and SSE-C parameters) and extra metadata fields, and includes a \PortableVisibilityConverter\ for handling ACL-to-visibility mapping. The package also ships with a test suite and a \S3ClientStub\ for mocking AWS interactions during testing.

src/AsyncAwsS3 · high confidence

Added a new \bin/\ directory containing utility scripts to support the project's sub-split architecture. \check-versions.php\ validates that extracted package dependencies are compatible with the main \composer.json\ and the target release version, while \set-flysystem-version.php\ updates version constraints across all sub-split \composer.json\ files. Additionally, \update-subsplit-closers.php\ synchronizes GitHub workflow files to sub-split repositories, and \close-subsplit-prs.yml\ automates the closing of pull requests submitted to read-only sub-split branches.

bin · high confidence

A new \League\\Flysystem\\UnixVisibility\ module has been introduced, containing a \VisibilityConverter\ interface and a \PortableVisibilityConverter\ implementation. This allows users to configure specific file and directory permissions (e.g., 0644/0755 for public, 0600/0700 for private) and provides a \fromArray\ factory method for custom permission maps. The module also includes comprehensive tests for visibility determination, inverse mapping, and default directory handling.

src/UnixVisibility · high confidence

This change introduces a new URL generation component within the \UrlGeneration\ namespace, providing a structured way to generate public and temporary URLs for stored files. It defines the \PublicUrlGenerator\ and \TemporaryUrlGenerator\ interfaces, along with concrete implementations: \PrefixPublicUrlGenerator\ for simple URL prefixing, \ShardedPrefixPublicUrlGenerator\ for distributing URLs across multiple prefixes using CRC32 hashing, and \ChainedPublicUrlGenerator\ to attempt multiple generators in sequence until one succeeds. These additions enable more flexible and robust URL generation strategies for users.

src/UrlGeneration · high confidence

A new \ReadOnlyFilesystemAdapter\ is available in the \src/ReadOnly\ package, allowing users to wrap an existing Flysystem adapter to enforce read-only access. This adapter delegates all read operations (such as \read\, \listContents\, and metadata retrieval) to the underlying adapter, but throws specific exceptions (e.g., \UnableToWriteFile\, \UnableToDeleteFile\) for any write, delete, move, copy, or visibility-changing operations. It also supports public URL generation, temporary URL generation, and checksum calculation by delegating to the wrapped adapter if it implements the respective interfaces (\PublicUrlGenerator\, \TemporaryUrlGenerator\, \ChecksumProvider\), or falling back to stream-based calculation for checksums.

src/ReadOnly · high confidence

The PathPrefixedAdapter now implements the PublicUrlGenerator, TemporaryUrlGenerator, and ChecksumProvider interfaces, allowing it to delegate public URL generation, temporary URL generation, and checksum calculation to the underlying adapter while correctly applying the path prefix. This means users can generate signed URLs and file checksums through the prefixed adapter without manually adjusting paths.

src/PathPrefixing · high confidence

The repository has been restructured to support sub-split publishing, moving adapter source code into separate packages (e.g., flysystem-ftp, flysystem-sftp-v3) while keeping the core library. This change introduces new configuration files for subsplit publishing, PHPStan, and PHP-CS-Fixer, updates the PHPUnit bootstrap to include mocked functions for testing, and adds a docker-compose setup for local development of FTP, SFTP, and WebDAV services. Additionally, the project now includes a Code of Conduct and a Security policy document.

(repo-wide) · high confidence

The SFTP adapter implementation using the phpseclib V2 library (located in src/PhpseclibV2) is now deprecated as of Flysystem 3.0. All classes in this namespace, including the SftpAdapter, SftpConnectionProvider, and associated exception classes, now carry deprecation notices directing users to migrate to the corresponding classes in the League\\Flysystem\\PhpseclibV3 namespace. The adapter's functionality remains available for existing users but will be superseded by the V3 implementation.

src/PhpseclibV2 · high confidence

The FTP adapter has been rewritten to improve reliability and compatibility. It now features a dedicated connection provider and a configurable connectivity checker (defaulting to a NOOP command) to proactively detect and recover from dropped connections. The adapter automatically disconnects on destruction and allows explicit disconnection. Path handling has been refined to resolve the connection root for accurate prefixing, and the adapter now supports empty root directories. Additionally, Unix directory listing timestamps are normalized to prevent future dates when the year is omitted, and the adapter supports both standard FTP and Pure-FTPd servers with specific escaping and list option handling.

src/Ftp · high confidence

Added test infrastructure for FTP and SFTP server connectivity checks; Updated SFTP test fixtures with new keys and configuration.

The Flysystem package has been restructured into a monorepo with individual sub-packages for each adapter (e.g., \league/flysystem-aws-s3-v3\, \league/flysystem-ftp\, \league/flysystem-sftp-v3\), allowing users to install only the storage drivers they need. The core \league/flysystem\ package now requires PHP 8.0.2 or higher and depends on \league/flysystem-local\ and \league/mime-type-detection\. Several adapters have been updated to support newer major versions of their underlying libraries, such as \async-aws/s3\ (v1–v3), \google/cloud-storage\ (v1–v2), and \mongodb/mongodb\ (v1–v2). Additionally, the SFTP adapter has been split into v2 and v3 variants, with the v2 version marked as abandoned in favor of \league/flysystem-sftp-v3\. Dependency conflicts have been added to prevent usage of buggy versions of \symfony/http-client\, \guzzlehttp/ringphp\, \guzzlehttp/guzzle\, and \aws/aws-sdk-php\.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 32 → 73 (+41.9)
• Rubric changed (rubric-2026.08.15 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 99 → 100 (+1.2)
• Architecture 94 → 98 (+4.3)
• Maturity 55 → 69 (+14.0)
• Readiness 11 → 71 (+60.3)
• Security 25 → 70 (+44.4)

• Coverage not measured — test suite did not build
• Dimension evaluation failed
• Duplicated block (5 lines × 2) (src/Ftp/FtpAdapterTestCase.php)
• Duplicated block (6 lines × 2) (src/WebDAV/WebDAVAdapterTestCase.php)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• …and 25 more

• Boundary-crossing change coupling: FtpAdapter.php ↔ SftpAdapter.php (src/Ftp/FtpAdapter.php)
• Boundary-crossing change coupling: InMemoryFilesystemAdapter.php ↔ LocalFilesystemAdapter.php (src/InMemory/InMemoryFilesystemAdapter.php)
• Dependency hygiene PARTLY measured — Composer dependencies read, no committed lock to grade for currency
• Documentation: no installation or build instructions
• Further sole-owners (lower concentration)
• High IaC: WD-COMPOSE-0002 (docker-compose.yml)
• High IaC: WD-COMPOSE-0002 (docker-compose.yml)
• High IaC: WD-COMPOSE-0002 (docker-compose.yml)
• High IaC: WD-COMPOSE-0002 (docker-compose.yml)
• High IaC: WD-COMPOSE-0002 (docker-compose.yml)
• High IaC: WD-COMPOSE-0002 (docker-compose.yml)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• …and 12 more

• 19 commits — 10 feature/other, 9 fixes

• (repo) — 7 commits
• (root) — 3 commits
• .github/workflows — 2 commits
• src/Ftp — 2 commits
• src/AwsS3V3 — 1 commit
• src/Local — 1 commit
• src/PhpseclibV2 — 1 commit
• src/PhpseclibV3 — 1 commit
• src/WhitespacePathNormalizer.php — 1 commit

• fix: Fix FTP lastModified() reporting a future year (#1857)
• fix: Fixed borked merge
• fix: Merge branch '3.x' into fix/ftp-root-null
• fix: Merge branch 'bdtripp-fix/ftp-root-null' into 3.x
• fix: Merge pull request #1916 from lazerg/fix/issue-1915-delete-race
• fix: Merge pull request #1917 from wakqasahmed/fix/ftp-lastmodified-year-1857
• fix: Merge pull request #1918 from maxhelias/fix/sftp-option
• fix: fix: do not fail deleting a local file that is already gone
• fix: fix: honor disableStatCache option in SftpConnectionProvider::fromArray
• change: Add multiple fingerprint formats
• change: Corrected release date
• change: Merge pull request #1908 from ghazalfaraj/3.x
• change: Merge pull request #1913 from cancan101/s3-populate-failure-reason
• change: Populate the failure reason on AwsS3V3Adapter exceptions
• change: Prep changelog
• change: Prpe changelog for release
• change: Report broken utf-8 as a corrupted path.
• change: Update email address
• change: Update github actions managed by me.

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

thephpleague/flysystem was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.