OneupFlysystemBundle: putting Flysystem adapters into a Symfony app

A filesystem abstraction behind a Symfony bundle

The OneupFlysystemBundle provides a Flysystem integration for Symfony projects, and the README explains the motivation in a sentence: Flysystem is a filesystem abstraction which allows you to easily swap out a local filesystem for a remote one.

That is the whole problem the bundle solves. A Symfony application that writes uploads to a local directory is fine until the deployment model changes, the traffic grows, or a second application needs the same files. At that point you either write the storage access behind an interface of your own, or you adopt a filesystem abstraction and let it carry the difference between a local path and a bucket.

The bundle's contribution is the Symfony side of that. It is the wiring that turns a configured adapter into a service your code can inject, so that the same application code works whether the environment points at a directory on disk or an object store. The README lists the adapters that can currently be configured, which is the practical surface of the bundle: Google Cloud Storage, AsyncAwsS3, AwsS3, AzureBlobStorage, Ftp, the local filesystem, and Sftp.

The audience is Symfony developers with a storage requirement, not PHP developers in general. The package is published on Packagist as oneup/flysystem-bundle, the licence is MIT, and the repository is not archived, with the last push on 2026-05-20.

The adapter list is the decision, and the S3 choice is a real one

Since the bundle configures Flysystem, the adapter list is effectively the feature list, and it is worth reading closely rather than as a shopping list.

Four of the seven are object stores: Google Cloud Storage, Azure Blob Storage, and two different S3 clients. The rest are filesystems in the classic sense: FTP, SFTP, and the local filesystem. The local adapter being in the list is the point of the whole abstraction, since it is what lets a development environment use a directory while production uses a bucket.

The two S3 entries deserve attention because they are not the same thing. AwsS3 is the AWS SDK for PHP, and AsyncAwsS3 is the separate AsyncAws project, which is a separate client rather than the AWS SDK's own client. Both talk to S3, and the choice comes down to which client your project already depends on and how you want errors and concurrency handled. Listing both means the bundle does not force the decision, but it also means the client dependency enters your dependency tree either way.

One detail the README does not explain is worth flagging. The repository topics include dropbox, gaufrette, gridfs, rackspace and replicate alongside the names in the adapter list, and gaufrette in particular is a different filesystem abstraction. The README's list of adapters you can configure is the authoritative statement, and it does not include those five, so the topics are broader than the documented feature set. Anyone evaluating support for a specific backend should check the documentation rather than the topic list.

The 4.x line tracks Flysystem 2 and 3, and 1.x users live on a branch

The banner at the top of the README announces that 4.x is available with Flysystem V2 and V3 support, and the last section explains what happens to everyone else: if you are looking for Flysystem 1.x support, check out the 3.x branch of the bundle.

That is a three way split, and it is the main operational fact about this project. Flysystem 1.x applications need the bundle's 3.x branch, Flysystem 2 and 3 applications want the current 4.x release, and the two lines are maintained separately, in separate branches, with separate documentation.

The reason is that Flysystem itself changed shape between 1.x and 2.x, and a bundle that configures adapters sits directly on top of that API. The adapter interfaces, the exception types and the way a filesystem is constructed all moved, so a bundle cannot support both without conditionals, and the maintainers chose to version the bundle in step with Flysystem instead.

For a team that is mid upgrade, that is a decision point rather than a detail. Moving from Flysystem 1 to 2 or 3 means moving from the bundle's 3.x branch to 4.x, and the configuration in your services or your package configuration is likely to change with it. The README does not include a migration guide, and the documentation directory referenced in the next section is where that material would live.

The README points at doc/index.md instead of documenting the setup

There is a deliberate brevity here, and the documentation entry point is stated plainly: it can be found in the file doc/index.md, and the README links to the documentation for the latest release with the same path.

So the README is an index rather than a manual. It tells you what the bundle is, which adapters exist, which branch serves which Flysystem major, where the documentation lives, and where to file issues. The setup instructions, the configuration keys and the service names are in the doc directory, which is part of the repository, and the linked path is version specific because it is read from the branch you are on.

That is a reasonable arrangement for a bundle, and it has one consequence worth planning around. Because the documentation is versioned with the code in the same repository, the docs you read are the docs for the branch you cloned, which is exactly what you want when the 3.x branch and the 4.x branch differ in configuration format. It does mean there is no single canonical page, and a search result that lands on the wrong branch will describe options that do not exist in your version.

The repository layout supports the same picture. The top level holds src/ for the bundle code, tests/ for the test suite, doc/ for the documentation, composer.json for the package definition, phpunit.xml.dist and phpstan.neon for the test and static analysis configuration, .php-cs-fixer.dist.php for code style, and .php-version for the PHP version the project targets.

The quality tooling is the maintainer's real specification

With a thin README, the configuration files in the tree tell you more about the project than the prose does, and they are all present.

phpstan.neon is the static analysis configuration, which means the bundle is checked by a static analyser rather than only by its test suite. phpunit.xml.dist is the test configuration, and the tests/ directory holds the test suite, so the bundle has one. .php-cs-fixer.dist.php defines the code style rules, which in a Symfony bundle matters more than it looks, because the style of a bundle is the style its users will copy when they override a template or extend a class.

.php-version pins the PHP version the project works against, and that file is the one to read before you plan an upgrade, because a bundle that raises its PHP floor does so in a minor release rather than a major one more often than not, and a bundle with a phpstan level to maintain and a test suite to keep green is one where the maintainers will not cut a release that breaks.

The CI badge in the README points at a workflow that runs on the repository, so the test suite and the static analysis are checked on every change rather than only when someone remembers.

There is also a small piece of process advice in the README that is worth following. When reporting a bug, it says it may be a good idea to reproduce it in a basic project built with the symfony/website-skeleton so that maintainers can reproduce the issue by cloning it and following a few steps. That is a request for a minimal reproducer, and it tells you what the maintainers consider a usable bug report.

Where the bundle is the wrong tool

There are three clear cases where using this bundle is a mistake, and they are worth separating.

The first is a project that does not use Symfony. The bundle is a Symfony bundle, so the wiring it provides is a Symfony wiring. Outside Symfony, you would use Flysystem directly, and the bundle adds nothing.

The second is a project that needs a backend the adapter list does not cover. The documented adapters are Google Cloud Storage, AsyncAwsS3, AwsS3, AzureBlobStorage, Ftp, local filesystem and Sftp. Flysystem itself has a larger adapter ecosystem, and in the general case you can register an adapter that the bundle does not ship, but that is you writing the service definition, which is exactly the work the bundle exists to save you. If your storage target is outside the list, the bundle stops being the cheap option.

The third is a project that wants full control of how the filesystem is constructed. The bundle configures Flysystem for you, which is convenient and also opinionated. A team that needs a custom adapter, a decorated filesystem, a different exception policy or a service it constructs with its own lifetime has to work around the bundle rather than use it.

The alternative in every one of those cases is the same: use Flysystem directly and define the filesystem service yourself in the Symfony container. The difference in approach is that the bundle gives you configuration driven setup and a set of ready made service definitions, while the direct route gives you a small amount of wiring to write once and full control over everything afterwards. For most applications the bundle is the better trade, and for the cases above it is not.

Editorial conclusion

OneupFlysystemBundle fits a Symfony application that needs to store files somewhere other than the local disk and would rather configure that than wire the Flysystem services by hand, and it does not fit a project on an older Symfony or Flysystem line, or one that needs storage behaviour the adapter list does not cover. Before adopting it, read doc/index.md for the current release, confirm your application runs on a Symfony and PHP combination the 4.x line supports, and check which Flysystem major your other dependencies pin.

Frequently asked questions

Official sources

1. 1up-lab/OneupFlysystemBundle on GitHub
2. Issues
3. License: MIT
4. README