Gaufrette

Gaufrette is a PHP library that provides a unified filesystem abstraction layer, letting you read, write, and manage files without knowing or caring where they physically live. A single Filesystem API sits on top of pluggable adapters for the local disk, Amazon S3, Azure Blob Storage, Google Cloud Storage, FTP/SFTP, in-memory arrays, ZIP archives, GridFS, and more.

By decoupling your application code from the underlying storage engine, Gaufrette lets you switch a project from local files to S3 (or any other backend) by changing only the filesystem definition, with zero impact on the code that actually reads and writes files. It is widely used across the Symfony ecosystem for media and document management.

What You Get

• A unified Filesystem API with read, write, has, delete, rename, and keys operations
• A rich set of built-in adapters: Local, AwsS3, AsyncAws S3, Azure Blob Storage, Google Cloud Storage, FTP, SFTP, GridFS, InMemory, and Zip
• A PHP stream wrapper so filesystem contents can be accessed via standard fopen-style stream URLs
• Metadata, checksum, and MIME-type support for adapters that expose it
• Symfony integration via the companion KnpGaufretteBundle

Common Use Cases

• Storing user-uploaded media so the storage backend can migrate from local disk to S3 without code changes
• Abstracting document/attachment storage in a Symfony application
• Writing tests against an in-memory filesystem instead of the real disk or a cloud provider
• Serving files transparently from FTP, SFTP, or cloud object storage behind one API

Under The Hood

Architecture - Gaufrette centers on a thin Filesystem class (src/Gaufrette/Filesystem.php) that implements FilesystemInterface and delegates every operation to an injected Adapter. The Adapter interface defines the storage contract (read, write, exists, keys, mtime, delete, rename, isDirectory), and optional capability interfaces like ListKeysAware, MetadataSupporter, ChecksumCalculator, and MimeTypeProvider let individual adapters advertise extra behavior. A FilesystemMap registers named filesystems, and a StreamWrapper bridges any filesystem to PHP’s native stream API.

Tech Stack - Pure PHP targeting PHP 7.4 and 8.x, distributed as a Composer library with PSR-0 autoloading under the Gaufrette namespace. It has no hard runtime dependencies; cloud adapters pull their SDKs (AWS SDK, Azure, Google Cloud) only when used, increasingly via dedicated adapter metapackages. Dev tooling includes phpspec, PHPUnit, PHPStan, Psalm, and php-cs-fixer.

Code Quality - The codebase is small, well-namespaced, and interface-driven, with static analysis baselines for both PHPStan and Psalm. Behavior is covered by an extensive phpspec suite under spec/ plus functional tests under tests/, giving good confidence across the many adapters.

API Design - The public surface is deliberately minimal: construct an adapter, wrap it in a Filesystem, and call intuitively named methods. Swapping storage backends is a one-line change, and the stream-wrapper option lets legacy code that expects file paths work unchanged. Documentation and per-adapter metapackages keep onboarding low-friction.