A bundle to create failover Flysystem adapters.

v0.4.2 2023-01-16 14:37 UTC

This package is auto-updated.

Last update: 2023-03-16 15:02:18 UTC


Source code Software license GitHub issues Test status Psalm coverage Psalm level Infection MSI

This bundle allows creating failover Flysystem adapters and provides tooling to keep underlying storages synchronized.

💡 Tip: you may want to use this bundle through webalternatif/flysystem-dsn-bundle, which makes the configuration much easier.

How it works

This bundle allows you to create failover adapters for Flysystem. A failover adapter is an adapter that is built upon multiple (already existing) adapters.

When you use a failover adapter, it will forward method calls to inner adapters.

  • For reading, it will use the first that works.
  • For writing, it will use the first that works and will push messages into a repository to keep underlying storages of all adapters synchronized.

Messages in the repository can then be asynchronously processed by a console command call (see Processing messages section).


Make sure Composer is installed globally, as explained in the installation chapter of the Composer documentation.

Applications that use Symfony Flex

Open a command console, enter your project directory and execute:

$ composer require webalternatif/flysystem-failover-bundle

Applications that don't use Symfony Flex

Step 1: Download the Bundle

Open a command console, enter your project directory and execute the following command to download the latest stable version of this bundle:

$ composer require webalternatif/flysystem-failover-bundle

Step 2: Enable the Bundle

Then, enable the bundle by adding it to the list of registered bundles in the config/bundles.php file of your project:

// config/bundles.php

return [
    // ...
    Webf\FlysystemFailoverBundle\WebfFlysystemFailoverBundle::class => ['all' => true],



Failover adapters are configured under the webf_flysystem_failover.adapters Symfony config path, and are then available as services with id webf_flysystem_failover.adapter.{name}.

Each failover adapter must have at least 2 inner adapters. An inner adapter could be a string to reference a service id, or an array with the following attributes:

  • service_id: (required) identifier of the inner adapter service,
  • time_shift: a time shift for when the synchronization command compares modification dates between inner adapters.

Message repository is customizable under the webf_flysystem_failover.message_repository_dsn Symfony config path. For now, only doctrine://<connection_name> and service://<service_id> are available.

        adapter1: # service: webf_flysystem_failover.adapter.adapter1
                - service_id_of_adapter_1
                - service_id: service_id_of_adapter_2
                  time_shift: 7200 # underlying storage of this adapter use a +02:00 timezone

        adapter2: # service: webf_flysystem_failover.adapter.adapter2
                - service_id_of_adapter_3
                - service_id_of_adapter_4
                - service_id_of_adapter_5

    message_repository_dsn: doctrine://my_connection

Run bin/console config:dump-reference webf_flysystem_failover for more info.

Processing messages

To process messages created by failover adapters, the following command is available:

$ bin/console webf:flysystem-failover:process-messages

It will process and remove the oldest messages present in the repository.

Listing messages to be processed

To list messages without removing them from the repository, run the following command:

$ bin/console webf:flysystem-failover:list-messages

Results are paginated by default, you can use --limit (-l) and --page (-p) to configure pagination.

If symfony/serializer is installed, the --format (-f) becomes available and allows you to display output in csv, json or xml.

Use --help for more info.

Synchronize existing storages

If you start to use this bundle on an existing project, you may want to manually synchronize an existing non-empty storage with other new empty ones.

It is possible with the following command:

$ bin/console webf:flysystem-failover:sync

Use --help for more info.


To run all tests, execute the command:

$ composer test

This will run Psalm, PHPUnit, Infection and a PHP-CS-Fixer check, but you can run them individually like this:

$ composer psalm
$ composer phpunit
$ composer infection
$ composer cs-check