PHPackages                             bushbaby/flysystem - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [File & Storage](/categories/file-storage)
4. /
5. bushbaby/flysystem

ActiveLibrary[File & Storage](/categories/file-storage)

bushbaby/flysystem
==================

Laminas Framework module bridge for flysystem filesystem.

8.0.2(2y ago)37406.1k↑24.7%174MITPHPPHP ^8.0CI failing

Since Nov 6Pushed 2y ago5 watchersCompare

[ Source](https://github.com/bushbaby/BsbFlysystem)[ Packagist](https://packagist.org/packages/bushbaby/flysystem)[ RSS](/packages/bushbaby-flysystem/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (27)Versions (33)Used By (4)

BsbFlysystem
============

[](#bsbflysystem)

A simple Laminas module that bridges the Flysystem filesystem.

[![Latest Stable Version](https://camo.githubusercontent.com/29e01f409abfff8567cb7bf89bb441e54803105a62099977e769d2a1ed65fc08/687474703a2f2f706f7365722e707567782e6f72672f62757368626162792f666c7973797374656d2f76)](https://packagist.org/packages/bushbaby/flysystem)[![Total Downloads](https://camo.githubusercontent.com/5ececdae0fc83c76b32b2fe8b598c72ac61f98fcce0109cdb0b19de9a07cc7c6/687474703a2f2f706f7365722e707567782e6f72672f62757368626162792f666c7973797374656d2f646f776e6c6f616473)](https://packagist.org/packages/bushbaby/flysystem)[![License](https://camo.githubusercontent.com/377be390933404ebd68f785b3ed7d81991a46cbb8b34c430e81e3712b2c7d273/687474703a2f2f706f7365722e707567782e6f72672f62757368626162792f666c7973797374656d2f6c6963656e7365)](https://packagist.org/packages/bushbaby/flysystem)[![PHP Version Require](https://camo.githubusercontent.com/19e4f5f5092b7ac0cf84abba396dd3c731d9b08d47b88e49c3b432dcc1603ebc/687474703a2f2f706f7365722e707567782e6f72672f62757368626162792f666c7973797374656d2f726571756972652f706870)](https://packagist.org/packages/bushbaby/flysystem)[![Test](https://github.com/bushbaby/BsbFlysystem/actions/workflows/test.yml/badge.svg)](https://github.com/bushbaby/BsbFlysystem/actions/workflows/test.yml)[![Coverage Status](https://camo.githubusercontent.com/9bfa329ebcf2f8bf1d7b4a924e6d6988b47cdda122079537ba8a7df04a50a4f8/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f62757368626162792f427362466c7973797374656d2f62616467652e7376673f6272616e63683d6d6173746572)](https://coveralls.io/github/bushbaby/BsbFlysystem?branch=master)

Provides a way to configure the various filesystem adapters provided by thephpleague's 'Flysystem'. And allows to retrieve fully configured filesystems by name from the ServiceLocator. Whether the defined filesystems are local- or dropbox filesystems becomes a configuration detail.

Installation
------------

[](#installation)

```
composer require bushbaby/flysystem

```

Then add `BsbFlysystem` to the `config/application.config.php` modules list.

Copy the `config/bsb_flysystem.local.php.dist` to the `config/autoload` directory to jump start configuration.

Deprecations
------------

[](#deprecations)

- dropped support for [FlySystem](https://flysystem.thephpleague.com/docs/) v1 and v2
- dropped support for [EventableFilesystem](https://github.com/thephpleague/flysystem-eventable-filesystem)
- dropped support for [CachedAdapter](https://github.com/thephpleague/flysystem-cached-adapter)
- dropped support for [Laminas Service Manager v2](https://docs.laminas.dev/laminas-servicemanager/migration)
- dropped support for [Null Adapter](https://github.com/thephpleague/flysystem/issues/1303)
- dropped support for [VFS Adapter](https://github.com/thephpleague/flysystem-eventable-filesystem)
- dropped support for [RackSpace Adapter](https://github.com/thephpleague/flysystem-rackspace)
- dropped support for [Plugin System](https://flysystem.thephpleague.com/docs/what-is-new/)

Migrating to v8
---------------

[](#migrating-to-v8)

Configuration changes

- For the adapter configuration the 'type' key has been renamed to 'factory'. Each adapter is now referenced by its FQCN in a 'factory' key.
- The 'options' is now passed to the adapter factory as an named arguments array. Look at individual adapter constructor which opions are available. Some options - such as 'mimeTypeDetector' may be a valid service names. The adapter will pull an instance from the service manager.
- The 'shared' option has been removed. Both the filesystem- and adapter service are plugin managers. Services pulled from a Laminas Plugin Manager with additional creation options are using the build method of the service manager and are thus not shared.
- The 'adapter\_map' has been removed. The adapter configuration is now done in the 'adapters' key. The 'adapter\_map' was used to overload the default adapter list. This is no longer needed as the default adapter list is now empty.
- And ofcourse look at the api changes from Flysystem [Upgrade from 1.x ](https://flysystem.thephpleague.com/docs/upgrade-from-1.x/) and [new in Flysystem V2 & V3](https://flysystem.thephpleague.com/docs/what-is-new/)

Configuration
-------------

[](#configuration)

Configuration regarding BsbFlysystem lives in the top-level configuration key `bsb_flysystem`.

The configuration consists of the following base elements;

- *Adapters* are consumed by a Filesystem.
- *Filesystems* filesystem are consumed in userland.

### Adapters

[](#adapters)

To configure an adapter you add a key to `bsb_flysystem->adapters` with a associative array containing the following options;

- factory <string> The FQCN of a factory used to create an adapter.
- options <array> named arguments passed to each adapter constructor (see [flysystem](http://flysystem.thephpleague.com) or peek into config/bsb\_flysystem.local.php.dist)
- options.prefix <string> (optional) Any filesystem adapter can be scoped down to a prefixed path using [Path Prefixing](https://flysystem.thephpleague.com/docs/adapter/path-prefixing/).
- options.readonly <boolean> (optional) Any filesystem adapter can be made read-only [Read only adapter](https://flysystem.thephpleague.com/docs/adapter/read-only/).

example: a readonly local adapter pointing to ./data/files

```
'bsb_flysystem' => [
    'adapters' => [
        'local_files' => [
            'factory' => BsbFlysystem\Adapter\Factory\LocalAdapterFactory::class,
            'options' => [
                'location' => './data/files',
                'readonly' => true,
            ],
        ],
    ],
],

```

### Filesystems

[](#filesystems)

Configure a filesystem by adding to `bsb_flysystem->filesystems`. Each filesystem may containing the following options;

- adapter <string> Name of adapter service.

```
'bsb_flysystem' => [
    'filesystems' => [
        'files' => [
	        'adapter' => 'local_files',
        ],
    ],
],

```

It is possible to override options given to the adapter factory via the 'adapter\_options' key. This is useful if you want to use the same adapter for multiple filesystems but with different options. Typically you would do that when you manually pull a filesystem or adapter from the a plugin manager.

#### AdapterManager

[](#adaptermanager)

The AdapterManager is automaticly configured, however it is possible to tweak its configuration via `bsb_flysystem->adapter_manager`.

In particular the lazy\_services configuration key may be useful if you use the Rackspace Adapter. BsbFlysystem loads that adapter 'lazily'. A connection is only established until you actually use the adapter. This done with help from [ProxyManager](https://github.com/Ocramius/ProxyManager). As Laminas also uses this libary we take advantage of the 'lazy\_services' configuration that may be available in your application. The Rackspace adapter merges the Laminas lazy\_services config key with the adapter\_manager lazy\_services config allowing control over how the ProxyManager handles it's thing.

```
'bsb_flysystem' => [
    'adapter_manager' => [
        'config'      => [
        ],
        'lazy_services' => [
            // directory where proxy classes will be written - default to system_get_tmp_dir()
            // 'proxies_target_dir'    => 'data/cache',
            // namespace of the generated proxies, default to "ProxyManagerGeneratedProxy"
            // 'proxies_namespace'     => null,
            // whether the generated proxy classes should be written to disk
            // 'write_proxy_files'     => false,
        ],
    ],
],

```

Usage
-----

[](#usage)

By default BsbFlysystem provides one pre-configured filesystem. This is a local filesystem and exposes the data directory of a default Laminas application. This directory is configured to have 'lazyRootCreation'.

Both the filesystem- and adapter services are Laminas Plugin Managers and stored within the global service manager. Aliases are registered for both; BsbFlysystemManager and BsbFlysystemAdapterManager.

### Filesystem Manager

[](#filesystem-manager)

In its simplest form this is how we would retrieve a filesystem. We get the filesystem service from the main service manager and fetch from that a filesystem instance.

example: Fetch a 'default' filesystem. In this case a 'local' filesystem with a root of 'data'.

```
$filesystem = $serviceLocator->get('BsbFlysystemManager')->get('default');
$contents   = $filesystem->read('file.txt');

```

If at some point you decide files need to be stored on a different system you simply reconfigure the named filesystem service to use a different adapter service. No need to change the userland implementation.

### Adapter Manager

[](#adapter-manager)

Direct access to the Adapter service is possible by via the `BsbFlysystemAdapterManager` service registered in the main service locator. This is useful to setup `Mount` Filesystems or to use runtime configuration. See the advanced section below.

```
$adapter    = $serviceLocator->get(\BsbFlysystem\Service\AdapterManager::class)->get('local_data');
$filesystem = new Filesystem($adapter);
$contents   = $filesystem->read('file.txt');

```

Provided Factories
------------------

[](#provided-factories)

I have tried to provide factories (and tests) for each of the adapters that come with the Flysystem. Each come with there own set of required and optional options. I refer to the Flysystem documentation for more information.

### Adapters

[](#adapters-1)

- Aws3Sv3
- AzureBlobStorage
- Dropbox
- Ftp
- GoogleCloudStorage
- InMemory
- Local
    - BsbFlysystem is preconfigured with an adapter named 'local\_data' to expose the ./data directory of a Laminas application.
- Replicate
- Sftp
- WebDAV
- ZipArchive

A note about the AwsS3 adapter; There are two versions of the AwsS3 sdk and only one can be installed at the same time. Therefore the Aws3S and Aws3Sv2 adapters are not required as dev-dependancies and are (at the moment) not unit tested.

### Filesystems

[](#filesystems-1)

There is one FilesystemFactory which creates a Filesystem based on the configuration.

Advanced Usage
--------------

[](#advanced-usage)

### Shared option and createOptions

[](#shared-option-and-createoptions)

A feature of Laminas service managers is the ability to create an instance of a service each time you request it from the service manager (shared vs unshared). As a convienence this can be easily accomplished by setting 'shared' to false/true. Together with 'createOptions' that can be provided to the get method of a service manager this is useful to override option values.

Consider the following configuration; Retrieve multiple configured dropbox filesystems based on stored accessTokens retrieved at runtime.

```
'adapters' => [
    'dropbox_user' => [
        'type' => 'dropbox',
        'options' => [
            'client_identifier' => 'app_id',
            'access_token'      => 'xxxxx',
        ],
    ],
],
'filesystems' => [
    'dropbox_user' => [
        'shared' => false,
        'adapter' => 'dropbox_user'
    ],
],
```

```
$accessTokens = [...];
foreach ($accessTokens as $accessToken) {
    $adapter = $serviceLocator->get(\BsbFlysystem\Service\AdapterManager::class)
                              ->get('dropbox_user', ['access_token' => $accessToken]);

    $filesystem = new Filesystem($adapter);
    $filesystem->put('TOS.txt', 'hi!');
}
```

Using the same createOptions feature but now directly from the Filesystem Manager. Notice the adapter\_options key which are passed to the Adapter Manager by the FilesystemFactory.

```
$accessTokens = [...];
foreach ($accessTokens as $accessToken) {
    $filesystem  = $serviceLocator->get(\BsbFlysystem\Service\FilesystemManager::class)
                                  ->get('dropbox_user', [
                                      'adapter_options' => ['access_token' => $accessToken]
                                  ]);

    $filesystem = new Filesystem($adapter);
    $filesystem->put('TOS.txt', 'hi!');
}
```

### Mount Manager

[](#mount-manager)

```
$sourceFilesystem = $serviceLocator->get(\BsbFlysystem\Service\FilesystemManager::class)->get('default'); // local adapter ./data
$targetFilesystem = $serviceLocator->get(\BsbFlysystem\Service\FilesystemManager::class)->get('archive'); // eg. zip archive

$manager = new League\Flysystem\MountManager(array(
    'source' => $sourceFilesystem,
    'target' => $targetFilesystem,
));

$contents = $manager->listContents('source://some_directory', true);
foreach ($contents as $entry) {
    $manager->write('target://'.$entry->path(), $manager->read('source://'.$entry->path()));
}
```

### RenameUpload filter

[](#renameupload-filter)

@since 1.3.0

`BsbFlysystem\Filter\File\RenameUpload` can be used to rename or move an uploaded file to a Flysystem filesystem.

This class takes an `filesystem` constructor option which must implement `League\Flysystem\Filesystem`.

The `BsbFlysystem\Filter\File\RenameUpload` extends `Laminas\Filter\File\RenameUpload` class so I refer to the Laminas [documentation](https://docs.laminas.dev/laminas-filter/file/#renameupload) for more information.

```
$request = new Request();
$files   = $request->getFiles();
// i.e. $files['my-upload']['tmp_name'] === '/tmp/php5Wx0aJ'
// i.e. $files['my-upload']['name'] === 'myfile.txt'

// get a filesystem from the BsbFlysystemManager (or construct one manually)
$filesystem = $serviceLocator->get(\BsbFlysystem\Service\FilesystemManager::class)->get('default');

$filter = new \BsbFlysystem\Filter\File\RenameUpload([
    'target' => 'path/to/file.txt',
    'filesystem' => $filesystem
]);

$filter->filter($files['my-upload']);
// or
$filter->filter('path/to/local/file.txt');

// File has been renamed and moved through $filesystem with key 'path/to/file.txt'
```

###  Health Score

48

—

FairBetter than 95% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity49

Moderate usage in the ecosystem

Community30

Small or concentrated contributor base

Maturity79

Established project with proven stability

 Bus Factor1

Top contributor holds 65.1% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~141 days

Recently: every ~253 days

Total

25

Last Release

804d ago

Major Versions

3.0.0 → 4.0.02017-09-05

4.0.1 → 5.0.02019-05-18

5.0.1 → 6.0.02020-02-19

6.0.0 → 7.0.02021-04-30

7.1.1 → 8.0.02023-01-06

PHP version history (6 changes)0.1.0PHP >=5.4

2.0.0-RC1PHP ^5.5 || ^7.0

4.0.0PHP ^7.0

5.0.0PHP ^7.2

7.0.0PHP ^7.3 || ^8.0

8.0.0PHP ^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/e42bb1eb4035d280d16210974fa60d0dbddeba8a061abec926e5e081d097231d?d=identicon)[bushbaby](/maintainers/bushbaby)

---

Top Contributors

[![basz](https://avatars.githubusercontent.com/u/143068?v=4)](https://github.com/basz "basz (188 commits)")[![snapshotpl](https://avatars.githubusercontent.com/u/312655?v=4)](https://github.com/snapshotpl "snapshotpl (42 commits)")[![svycka](https://avatars.githubusercontent.com/u/1270782?v=4)](https://github.com/svycka "svycka (27 commits)")[![FnTm](https://avatars.githubusercontent.com/u/1011549?v=4)](https://github.com/FnTm "FnTm (5 commits)")[![eivydas](https://avatars.githubusercontent.com/u/23526632?v=4)](https://github.com/eivydas "eivydas (5 commits)")[![jguittard](https://avatars.githubusercontent.com/u/5320213?v=4)](https://github.com/jguittard "jguittard (4 commits)")[![jaapio](https://avatars.githubusercontent.com/u/1060433?v=4)](https://github.com/jaapio "jaapio (3 commits)")[![electrolinux](https://avatars.githubusercontent.com/u/601587?v=4)](https://github.com/electrolinux "electrolinux (2 commits)")[![stefanotorresi](https://avatars.githubusercontent.com/u/2952427?v=4)](https://github.com/stefanotorresi "stefanotorresi (2 commits)")[![dependabot-preview[bot]](https://avatars.githubusercontent.com/in/2141?v=4)](https://github.com/dependabot-preview[bot] "dependabot-preview[bot] (2 commits)")[![carnage](https://avatars.githubusercontent.com/u/846596?v=4)](https://github.com/carnage "carnage (2 commits)")[![imonteiro](https://avatars.githubusercontent.com/u/3138089?v=4)](https://github.com/imonteiro "imonteiro (2 commits)")[![worthwhileindustries](https://avatars.githubusercontent.com/u/3536254?v=4)](https://github.com/worthwhileindustries "worthwhileindustries (1 commits)")[![bstoney](https://avatars.githubusercontent.com/u/1164857?v=4)](https://github.com/bstoney "bstoney (1 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")[![FrankHouweling](https://avatars.githubusercontent.com/u/1426973?v=4)](https://github.com/FrankHouweling "FrankHouweling (1 commits)")[![Orkin](https://avatars.githubusercontent.com/u/1061903?v=4)](https://github.com/Orkin "Orkin (1 commits)")

---

Tags

filesystemFlysystemlaminasmezzio

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/bushbaby-flysystem/health.svg)

```
[![Health](https://phpackages.com/badges/bushbaby-flysystem/health.svg)](https://phpackages.com/packages/bushbaby-flysystem)
```

###  Alternatives

[league/flysystem-aws-s3-v3

AWS S3 filesystem adapter for Flysystem.

1.6k263.6M790](/packages/league-flysystem-aws-s3-v3)[league/flysystem-local

Local filesystem adapter for Flysystem.

225231.8M39](/packages/league-flysystem-local)[oneup/flysystem-bundle

Integrates Flysystem filesystem abstraction library to your Symfony project.

64422.9M66](/packages/oneup-flysystem-bundle)[league/flysystem-bundle

Symfony bundle integrating Flysystem into Symfony applications

40129.5M87](/packages/league-flysystem-bundle)[league/flysystem-sftp-v3

SFTP filesystem adapter for Flysystem.

6129.6M91](/packages/league-flysystem-sftp-v3)[league/flysystem-memory

In-memory filesystem adapter for Flysystem.

8533.6M194](/packages/league-flysystem-memory)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)