KnpGaufretteBundle wires Gaufrette filesystems into Symfony config

A bundle that exists to remove service wiring

KnpGaufretteBundle is described simply as a Gaufrette integration for Symfony projects, and its entire value proposition sits in one sentence: you can declare your filesystems as services without reaching into the service container. Gaufrette itself is a PHP library providing a filesystem abstraction layer, which lets you write an application without needing to know where media files will be stored or how. That is the classic problem the bundle addresses. Without it, every consumer of your storage needs a service definition, and swapping from local disk to S3 means touching service configuration classes. With it, storage becomes configuration. The audience is Symfony developers who already have media or file handling in an application and want the storage backend to be a deployment concern rather than a code concern. This is a small bundle by design, and the repository layout matches that: a DependencyInjection directory for the extension, a Command directory, a FilesystemMap.php, the bundle class, Resources holding the documentation and templates, and Tests.

Adapters and filesystems are two separate layers of configuration

The configuration is divided into two parts, adapters and filesystems, and understanding why they are separate is what makes the design click. An adapter describes a backend, such as a local directory. A filesystem is a named instance built on top of an adapter, and it can carry an alias. So the adapter block declares where bytes live, and the filesystem block names that storage and points at the adapter. The adapter configuration for a local directory looks like this:

# config/packages/knp_gaufrette.yaml
knp_gaufrette:
    adapters:
        foo:
            local:
                directory: /path/to/my/filesystem

A filesystem then references that adapter by key:

# config/packages/knp_gaufrette.yaml
knp_gaufrette:
    adapters:
        # ...
    filesystems:
        bar:
            adapter:    foo
            alias:      foo_filesystem

Each filesystem must have an adapter whose value is an adapter key, so the link is explicit and a typo fails at compile time rather than at the first upload. The naming rule is worth noting too, because it determines what your service ids look like: the filesystem defined above results in a service with the id gaufrette.bar_filesystem, and the alias parameter lets you define an additional alias, foo_filesystem in this case. That derived service id is the part that couples your code to the bundle, and knowing it in advance saves hunting through a container dump later.

One map service returns every declared filesystem

The bundle exposes declared filesystems through a map service, and the example in the documentation retrieves a filesystem by the key it was declared under. For the bar filesystem declared above, the call is:

$container->get('knp_gaufrette.filesystem_map')->get('bar');

That returns the bar instance of Gaufrette\Filesystem. The design point is that consumers do not need to know the service id of each individual filesystem, only the map. That is what allows the same application code to work against different backends, since the key you ask for stays the same while the adapter behind it changes. It also means the filesystem name becomes a configuration-level identifier that appears in your code, so renaming one is a code change rather than a config change, which is a small cost worth planning for. For a Symfony application the map is normally injected rather than fetched from the container, and the documentation points to a separate use case examples document under Resources/docs for basic patterns.

Nineteen adapters, each installed as its own package

The adapter list is where the practical value shows, and the list is long: Local, Safe Local, Service, In Memory, Azure Blob Storage, GridFS, MogileFS, Ftp, Sftp, Phpseclib Sftp, Apc, AsyncAws S3, AWS S3, Open Cloud, GoogleCloudStorage, Cache, Stream Wrapper, Doctrine DBAL and Dropbox. The important operational detail is that adapters are separate packages. The installation notes say you need to install separately the adapters you want to use, with details in the Gaufrette metapackages for adapters page and the full list on packagist. So the bundle itself is small and the storage backends are opt in, one package per backend. That is a sound arrangement for a Symfony bundle because a shared library should not force a dependency on an S3 client or a GridFS extension, but it does mean a working setup needs a second install step that the bundle documentation treats as a prerequisite. If you install the bundle and find that a filesystem cannot be created, the missing adapter package is the first thing to check.

Registering the bundle and installing it

The bundle is installed with Composer under the package name knplabs/knp-gaufrette-bundle:

composer require knplabs/knp-gaufrette-bundle

It then has to be registered in the kernel, which the documentation describes as a required step rather than an optional one:

``` php <?php

return [ // ... Knp\Bundle\GaufretteBundle\KnpGaufretteBundle::class => ['all' => true], ]; ```

The all => true flag means the bundle is enabled in every environment, which is the sensible default for a storage integration since a filesystem that exists in one environment and not another tends to fail at runtime rather than at build time. The ordering in that list is also the conventional Symfony bundle registration position, after the framework bundles and before your own application bundles. The repository also carries a Dockerfile, a compose file and a Makefile, a .travis.yml for continuous integration, phpunit.xml.dist for the test suite, and the release-please tooling with .release-please-manifest.json and release-please-config.json, which is how the tagged versions are produced. A CHANGELOG.md and an UPGRADE.md are both maintained, and the presence of an UPGRADE file is the first thing to look at when moving between major versions.

The 1.0.0 jump and who is maintaining it

The release history explains the version number and the upgrade risk at the same time. The tagged versions are v0.10.0 on 2026-07-18, v0.7.3 on 2024-11-18, and then v1.0.0 on 2026-07-24, which is also the date of the last push to the repository. The 0.10.0 release and the 1.0.0 release are days apart, which reads like a decision to ship the accumulated 0.x work under a stable version number rather than a long gap in development. The repository is not archived, and the work is current as of 2026-07-24. What that date also means is that the 1.0.0 line is young, so any documentation or blog posts written against 0.x may describe configuration keys that no longer apply. The maintenance note is worth reading too. KNPLabs states that it is looking for maintainers, and the project documentation invites anyone interested to open a pull request to ask to be added as a maintainer. The project is MIT licensed with the licence file kept at the root, which is a permissive grant, though as always the licence covers the bundle code and not the adapters you install alongside it, each of which carries its own terms.

Editorial conclusion

Adopt KnpGaufretteBundle if you already use Gaufrette in a Symfony application and want storage backends declared in configuration rather than assembled in PHP, especially if you need more than one backend, since the adapter and filesystem split lets you swap storage without touching call sites. Do not reach for it if you only need one local directory, where a plain service is enough, or if you are starting a new project and would rather pick a filesystem abstraction that is not version 1.0.0. Before you plan an upgrade from 0.x, read UPGRADE.md, confirm the Gaufrette adapters you rely on are installed as separate packages, and check the PHP and Symfony versions your composer constraints actually allow.

Frequently asked questions

Official sources

1. KnpLabs/KnpGaufretteBundle on GitHub
2. License: MIT
3. Project website
4. README
5. Releases