# KnpLabs/Gaufrette: a PHP filesystem abstraction layer for swapping storage backends

> Gaufrette is a PHP library that puts a single filesystem interface in front of local disks, S3, FTP, SFTP, GridFS and more. It suits applications that expect their storage location to change; it does not suit you if you need the full feature set of a specific cloud SDK.

**KnpLabs/Gaufrette** — PHP library that provides a filesystem abstraction layer − will be a feast for your files!

- Repository: https://github.com/KnpLabs/Gaufrette
- Website: http://knplabs.github.io/Gaufrette
- Stars: 2,465 · Forks: 351
- Language: PHP
- License: MIT
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/knplabs-gaufrette

## The problem Gaufrette solves for PHP applications

Media in a PHP project tends to start on the local disk and end up somewhere else. The README frames this directly: the abstraction layer lets you build the application "without the need to know where all those media will be stored and how." That is the whole pitch. You write code against one interface, and the adapter behind it decides whether a file lands in a local directory, an S3 bucket, an FTP server or a GridFS collection.

The second half of the argument is migration. The README says that if a server reaches its limits, you can move media to Amazon S3 or another solution, and the only change is the filesystem definition, not the application code. That is a real constraint in PHP projects where uploads are scattered across controllers and services. Gaufrette is aimed at teams that expect storage to move, not at teams that have picked a backend and intend to stay there forever.

## How the adapter model works and where the third-party dependencies live

Gaufrette separates the filesystem interface from the adapter that implements it. The README lists the maintained adapters: AsyncAws S3, AwsS3, AzureBlobStorage, DoctrineDbal, Flysystem, Ftp, GoogleCloudStorage, GridFS, InMemory, Local, OpenCloud, PhpseclibSftp and Zip. Each has a named maintainer in the README table, except InMemory, Local and Zip, where the README says everyone on the list is considered a maintainer.

That table is the part worth reading before you commit. It tells you who to ping if an issue or pull request goes unanswered, which is a more useful signal than a download count. The adapter list also shows the shape of the dependency problem: an S3 adapter needs an AWS SDK, a GridFS adapter needs the MongoDB driver, and a Flysystem adapter sits on top of another abstraction library.

The README addresses this with metapackages. Every maintained adapter now has a dedicated metapackage on Packagist under the gaufrette/ vendor prefix, and the README states it highly recommends them because they carry their own requirements. In practice that means you install the adapter package and its third-party SDK comes with it, instead of you working out which version of which SDK to require first. The Makefile shows what the alternative looks like: its install-all-deps target requires aws/aws-sdk-php, google/apiclient, doctrine/dbal, league/flysystem, microsoft/azure-storage-blob, phpseclib/phpseclib, mongodb/mongodb and async-aws/simple-s3 in one go. That target exists to run the whole test suite, not to describe how an application should install Gaufrette.

## Installing Gaufrette with Composer and writing a first file

The README points at Packagist for the metapackage list and says to use the metapackages rather than assembling third-party dependencies by hand. The base package is KnpLabs/Gaufrette, so a Composer install of the library itself looks like this:

```bash
composer require knplabs/gaufrette
```

For a specific backend, the README directs you to the gaufrette/ packages on Packagist and says each metapackage contains its own requirements. The README does not print the individual package names, so check the Packagist page for the adapter you need before adding it to composer.json.

Once the package is in place, the pattern is to construct an adapter and wrap it in a filesystem. The README does not include a code sample, so the exact class names for your adapter come from the official documentation at knplabs.github.io/Gaufrette rather than from the repository README. What the README does establish is the boundary: your application talks to the filesystem object, and the adapter is the only place that knows about S3, FTP or a local path.

For a Symfony application, the README states that integration is available through KnpLabs/KnpGaufretteBundle, which is a separate package and the route to take if you want the filesystem registered as a service instead of constructed by hand.

## The development setup assumes Docker and a specific PHP version

The README's development section requires docker-ce and docker-compose, and the Makefile sets PHP_VERSION to 7.2 by default. The supported values listed in the README are 7.1, 7.2 and 7.3. The first step creates the environment file:

```bash
make docker.dev
```

That target copies .env.dist to .env, which you then configure. Building the PHP image and installing dependencies are separate targets:

```bash
make docker.build
make docker.all-deps
```

The docker-compose.yml file shows what gets started alongside PHP: a mongo service, an sftp service built from atmoz/sftp:alpine with the command gaufrette:gaufrette:::gaufrette, and an ftp service built from ./docker/ftp with PUBLICHOST set to ftp. Those services exist because the adapter test suite needs something to talk to.

One caveat is stated plainly in the README: the docker setup for PHP 7.3 is available, but the ssh2 extension is not installed because it was not available for PHP 7.3 at the time. If your work touches the SFTP adapter, that is the version to avoid in the test environment. Switching PHP versions also requires clearing dependencies first, with make clear-deps followed by PHP_VERSION=<the_version_you_want_to_use> make build install-deps.

## Where Gaufrette is the wrong tool

The abstraction cuts both ways. If you write against a single filesystem interface, you get the operations that interface exposes, and provider-specific behaviour is either normalized away or unavailable. Object tagging, lifecycle rules, presigned URL policies and storage-class transitions are S3 concepts with no equivalent in the Local or Zip adapters, so a library that promises to move you between backends cannot surface them without breaking that promise.

The README also does not document rollback, and there is no migration tooling described for moving existing files between adapters. Changing the filesystem definition in code is the easy part; copying the bytes is not something the README claims to handle. If you are mid-migration, that gap matters more than the interface does.

The maintainer table is a second limit. Most adapters have one named maintainer, and the README itself anticipates the failure mode by telling you to ping them if you do not get a timely response. For an adapter with a single referent, an unanswered issue is a real risk to weigh, particularly for the cloud adapters whose SDKs move on their own schedule.

Finally, the README carries a note stating that the project does not have any stable release yet, but that the maintainers do not want to break backward compatibility. That note sits alongside a v1.0.0 release dated 2026-07-22, with v0.11.1 before it in 2022. The README text appears not to have been updated to match, which is worth knowing if you are reading it as the current statement of project status.

## Gaufrette compared with using Flysystem directly

Flysystem appears in Gaufrette's own adapter list, which is the clearest statement of the relationship: Gaufrette can wrap Flysystem rather than replace it. The two solve the same problem from different directions. Flysystem is itself a filesystem abstraction with its own adapter ecosystem, and it is widely used independently of Gaufrette, so a team choosing between them is really choosing which abstraction's interface and adapter set fits the application.

Choosing Gaufrette means the Flysystem adapter is one option among many behind the same interface, which is useful if part of your storage is on FTP or GridFS and you want one API across all of it. It also means an extra layer if Flysystem is the only backend you ever intend to use, since the Flysystem adapter has to translate between two abstractions that cover similar ground. The Makefile pins league/flysystem to ^1.0 for the test suite, so the adapter targets that major line.

For Symfony projects specifically, the README names KnpLabs/KnpGaufretteBundle as the integration path, which is a concrete reason to prefer Gaufrette over wiring a standalone abstraction by hand.

## Licence and the cost of keeping adapters current

Gaufrette is MIT licensed, which permits commercial and closed-source use and requires preserving the copyright notice and licence text. The adapters are separate packages, so their licences and their third-party SDK licences apply independently. The Microsoft Azure, Google and AWS SDKs each carry their own terms, and the metapackage approach means those terms arrive with the adapter rather than being something you chose explicitly. This is a description of the arrangement, not legal advice; check the licence of each package you actually install.

Upgrade cost is dominated by those SDKs. The v1.0.0 release landed on 2026-07-22, and the previous release was v0.11.1 on 2022-11-03, so the jump from 0.11 to 1.0 is the migration to plan for. The Makefile's install-all-deps target shows the set of SDKs the test suite exercises, including aws/aws-sdk-php at ^3.158 and google/apiclient at ^2.12, and those constraints are the ones that will move under you. If your application only uses the Local or InMemory adapter, the upgrade surface is much smaller than if it depends on a cloud adapter with a fast-moving SDK underneath.

## Conclusion

Adopt Gaufrette when your PHP application reads and writes files through one interface and the storage location is expected to change, and install the metapackage for the adapter you actually use rather than pulling every third-party SDK. Skip it if you need provider-specific features such as S3 object tagging or lifecycle rules, because the abstraction is the point and it hides those. Before committing, check the adapter you need against the maintainer table in the README, confirm the metapackage name on Packagist, and read the changelog for the v1.0.0 release, since the README states the project had no stable release before it.

## FAQ

### What is KnpLabs/Gaufrette?

It is a PHP library that provides a filesystem abstraction layer, so an application can read and write files without knowing whether they live on a local disk, S3, FTP, SFTP, GridFS or another backend. The README lists the maintained adapters and a named maintainer for each.

### How do you install Gaufrette?

Install it with Composer. The README says every maintained adapter has a dedicated metapackage on Packagist under the gaufrette/ prefix and highly recommends using them, because each metapackage contains its own third-party requirements.

### Does Gaufrette have a stable release?

The README carries a note saying the project does not have any stable release yet, while the repository shows a v1.0.0 release dated 2026-07-22, following v0.11.1 in 2022. The README note appears not to have been updated to match.

### Is there a Symfony integration for Gaufrette?

Yes. The README states that Symfony integration is available through KnpLabs/KnpGaufretteBundle, which is a separate repository from the library itself.

### Which PHP versions does the Gaufrette development setup support?

The README lists 7.1, 7.2 and 7.3, with 7.2 as the default set in the Makefile. It notes that the PHP 7.3 docker setup does not install the ssh2 extension because it was not available for that version.

## Sources

- [KnpLabs/Gaufrette on GitHub](https://github.com/KnpLabs/Gaufrette)
- [License: MIT](https://github.com/KnpLabs/Gaufrette/blob/master/LICENSE)
- [Project website](http://knplabs.github.io/Gaufrette)
- [README](https://github.com/KnpLabs/Gaufrette/blob/master/README.md)
- [Releases](https://github.com/KnpLabs/Gaufrette/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/knplabs-gaufrette