PHP library that provides a filesystem abstraction layer − will be a feast for your files!

Related tags

php filesystem gaufrette


Gaufrette provides a filesystem abstraction layer.

Build Status AppVeyor Status Quality Score Packagist Version Total Downloads Software License Join the chat at Gitter

Why use Gaufrette?

Imagine you have to manage a lot of medias in a PHP project. Lets see how to take this situation in your advantage using Gaufrette.

The filesystem abstraction layer permits you to develop your application without the need to know where all those medias will be stored and how.

Another advantage of this is the possibility to update the files location without any impact on the code apart from the definition of your filesystem. In example, if your project grows up very fast and if your server reaches its limits, you can easily move your medias in an Amazon S3 server or any other solution.


Read the official Gaufrette documentation.

Metapackages for adapters

Every maintained adapter now have a dedicated metapackage. You can find the list on packagist. We highly recommend you to use them as they contain their own requirements: you don't need to worry about third-party dependencies to install before using Gaufrette anymore.

Symfony integration

Symfony integration is available through KnpLabs/KnpGaufretteBundle.


Here is the list of dedicated maintainer(s) for every adapter not deprecated. If you don't receive any response to your issue or pull request in a timely manner, ping us:

Adapter Referent
AsyncAws S3 @Nyholm
AwsS3 @NiR-
AzureBlobStorage @NiR-
DoctrineDbal @pedrotroller, @NicolasNSSM
Flysystem @nicolasmure
Ftp @fabschurt
GoogleCloudStorage @AntoineLelaisant
GridFS @NiR-
OpenCloud @NiR-
PhpseclibSftp @fabschurt

For InMemory, Local and Zip adapters everyone in this list is considered as a maintainer.


Requires the latest versions of :

  • docker-ce
  • docker-compose
  1. Create .env file :
$ make dev

and configure it as you want.

  1. Build the php docker image :
$ make build
  1. Install dependencies :
$ make install-deps
  1. Run tests :
$ make tests

You can also use a different php version, simply set the PHP_VERSION env var to any of these values when calling a make target :

See the docker-compose.yml file for more details.

You'll need to clear the previously installed dependencies when switching from a version to an other, to do so, run :

$ make clear-deps
$ PHP_VERSION=<the_version_you_want_to_use> make build install-deps
  1. Apply Coding Standards

You should check for CS violations by using

$ make php-cs-compare

and fix them with

$ make php-cs-fix


This project does not have any stable release yet but we do not want to break BC now.

  • Added AzureBlobStorage adapter

    Added AzureBlobStorage adapter

    Closes #158

    (Also added some small fixes to make the functional test pass)

    opened by lmammino 18
  • Added LazyRackspaceCloudfiles adapter

    Added LazyRackspaceCloudfiles adapter

    This pull request adds an adapter for Rackspace Cloudfiles that issues authentication only when needed to (Lazy authentication).

    opened by lmammino 16
  • Adding OpenStack adapter

    Adding OpenStack adapter

    Adding an adapter for OpenStack, used for example for Hubic, OVH personal cloud storage.

    opened by wysow 15
  • Copy files between file systems

    Copy files between file systems

    Is there any simple way to do this currently? Can't seem to find anything.

    opened by phillipsnick 15
  • Could not write the key content

    Could not write the key content

    I get the following error when I try to write an uploaded file my Amazon S3 bucket

    Could not write the "2014/04/24/53596551ee0ec.m4a" key content." at .../vendor/knplabs/gaufrette/src/Gaufrette/Filesystem.php line 113

    opened by jspizziri 13
  • Flysystem adapter

    Flysystem adapter

    As a bonus, I added "Implementing new Adapter" documentation.

    opened by umpirsky 13
  • Cannot use phpseclib\Net\SFTP as SFTP because the name is already in use in ../knplabs/gaufrette/src/Gaufrette/Adapter/PhpseclibSftp.php on line 6

    Cannot use phpseclib\Net\SFTP as SFTP because the name is already in use in ../knplabs/gaufrette/src/Gaufrette/Adapter/PhpseclibSftp.php on line 6

    I get the following error when using Gaufrette in a Symfony 2.4 environment when i do a cac:clear:

    Cannot use phpseclib\Net\SFTP as SFTP because the name is already in use in ../knplabs/gaufrette/src/Gaufrette/Adapter/PhpseclibSftp.php on line 6

    I'm using the following versions:

    knplabs/gaufrette | 0.2.1 knplabs/knp-gaufrette-bundle | 0.2.0

    opened by playr1983g 12
  • implemented fast listKeys for gridfs

    implemented fast listKeys for gridfs

    as proposed in #118 . Filesystem now checks if adapter has listKeys method (no need to implement it for all adapters, imho, since filesystem/ftp traversing is not subject to optimization), gridfs implements listKeys via MongoRegex.

    I also added a typehint to FunctionTest $filesystem property.

    @l3l0 , please check it this PR complies to your thoughts about Gaufrette. If it's ok, I'll propapbly implement it also for doctrine via LIKE (is also should be applicable to S3 / Rackspace, but I've no posibillity to test that).

    opened by andrewtch 12
  • [Feature] Support for multi-container Azure workflow

    [Feature] Support for multi-container Azure workflow

    Currently, the AzureBlobStorage adapter requires a single container name which will be filesystem root, it might try to create it.

    If I'm using a single storage account to hold only one type of asset (say, only images), I'd like to use one container per image (which will hold the original and all the variants), much like for example Azure Media Services does. This also seems to be a recommended way of doing things.

    What could be done here is add an additional flag / mode which would take the storage key and use the part until the first slash, create a container (if it doesn't already exist) and use the rest of the path as key. Ie.

    write('my/image/path.jpeg') // "my" = container, "image/path.jpeg" = key

    Some sort of container default creation options should also be provided (for example, access mode), but I think it shouldn't be all that hard.

    opened by dkarlovi 12
  • Initial MogileFS Adapter

    Initial MogileFS Adapter

    Hi again

    My colleague @mtarvainen has now finished an initial version of MogileFS adapter. Would you be interested in pulling that in?

    I know tests are still missing but we're going to make them 'soon'. Anyway, I was told that at least the basic functionality should be ok.

    opened by TomiS 12
  • Add a .gitattributes file

    Add a .gitattributes file


    Remove everything that is related to tools, github, docker, CIs Keep the tests for people packaging this lib and the phpunit config file. Also keep source files, but nothing more.

    opened by williamdes 0
  • Local issue Operation not permitted

    Local issue Operation not permitted

    How I can ignore directory who does not have read/write permission to trigger

    RecursiveDirectoryIterator::__construct(/MyDir/.Trashes): failed to open dir: Operation not permitted


    opened by Webonaute 0
  • Deprecated adapters removed in incorrect version

    Deprecated adapters removed in incorrect version

    Hi, Just updated an application and found major breakages, tracked it down to this plugin.

    The Adapters have been warning about deprecation since 0.4:

    @trigger_error('The ' . __NAMESPACE__ . '\Cache adapter is deprecated since version 0.4 and will be removed in 1.0.', E_USER_DEPRECATED);

    This is completely fine, but they didn't get removed in 1.0.0, they were removed in 0.10.0 (tagged just over a month ago). So their removal was completely unexpected and caused a BC break (it's also a SemVer violation).

    Locking down our composer.json to the older version until all dependencies have caught up is a simple workaround, but it's worth noting in case others have the same problem. Our composer.lock file says we upgrade from 0.9.0 to 0.10.0.

    tldr: 0.1.0 !== 1.0.0

    opened by chrisaligent 2
  • Test on PHP8

    Test on PHP8

    Just for fun. Let's see if it passes.

    opened by Nyholm 0
  • Add Flysystem Adapter isDirectory support

    Add Flysystem Adapter isDirectory support

    I was struggling to use a mixture of gaufrette with liip imagine and \Superbalist\Flysystem\GoogleStorage\GoogleStorageAdapter.

    The missing key to use \Gaufrette\Adapter\Flysystem was that Gaufrette\Stream\InMemoryBuffer uses $this->filesystem->isDirectory($this->key) in stat(), which fails in \Gaufrette\Adapter\Flysystem due to UnsupportedAdapterMethodException('isDirectory is not supported by this adapter.') in isDirectory().

    The way i solved this is by extending the \Gaufrette\Adapter\Flysystem and overwriting

        public function isDirectory($key)
            return $this->adapter->has($key.'/');

    This is the same method as in \Gaufrette\Adapter\GoogleCloudStorage

    Hope this helps somebody. Does it make sense to create a pull request?

    opened by floplus 0
  • Remove reset call

    Remove reset call

    opened by chadyred 1
  • [1.0] Openstack error File not found when `setMetadata` and call `resetMetadata`

    [1.0] Openstack error File not found when `setMetadata` and call `resetMetadata`


    @nicolasmure I followed the development of the new OpenStack adapter. I try it on the bundle and I make an issue on it but it seems this errors is link to this package.

    I have try to use this branch on KnpGaufretteBundle (by redefining opencloud service for this new one).

            class: Gaufrette\Adapter\OpenStack
            abstract: true
            arguments: ["first", "second", "third", "fourth"]
            class: OpenStack\OpenStack
                    tokenId: "%openstack_token%"
                    region: "%openstack_object_storage_region%"
                    authUrl: "%openstack_identity_url%"
                    username: "%openstack_username%"
                    password: "%openstack_password%"
                    tenantName: "%openstack_tenant_name%" # v3 use toeken, v2 user authentication username
                    tenantId: "%openstack_tenant_id%"
                    debugLog: true
                    user: { name: "%openstack_username%", password: "%openstack_password%", domain: { id: 'default', name: 'Default' } }
                    scope: { project: { name: "%openstack_project_name%", id: "%openstack_project_id%", domain: { id: 'default', name: 'Default' }} }

    But an error appear on setMetadata, the resetMetadata method return a FileNotFound on OpenStack 1-x branch for KnpGaufrette.


    If I remove the resetMetadata call all works great !

    Like this :

    opened by chadyred 4
  • Big file issue

    Big file issue


    i am trying to download and upload files from S3 to local filesystem and vice versa using Knp Gaufrette in a Symfony project.

    My code work run on a container in openshift and work fine for little files but with large file (1Go) i have memory issues. I am limited to 1,5Go in my container. I don't understand why my memory is growing so high. Maybe i don't understand well the concept of stream in php but i thought that the file wasn't loaded in memory with stream but loaded chunk by chunk. With my code i can see that when i do$srcStream = $this->fs_s3->createStream($filename); $srcStream->open(new StreamMode('rb+')); my memory is growing with the size of the file. I also tried copy('gaufrette://s3/'.$filename,'gaufrette://nfs/'.$filename); but is is the same.

    Am i using stream in the wrong way? Any advice?

    Thank you in advance for your help. Regards

    opened by lyandr 0
  • AwsS3 Fix rename method for url not safe source

    AwsS3 Fix rename method for url not safe source

    The rename method fails when using non url safe chars in the source parameter.

    Error executing "CopyObject" on "https://****"; AWS HTTP error: Client error: PUT resulted in a 400 Bad Request response: InvalidArgumentInvalid copy source encoding.x-amz-copy-source</Argu (truncated...)

    I just url encode the CopySource parameter in the API call

    opened by alexgt9 0
  • StreamWrapper, write called twice

    StreamWrapper, write called twice

    I was testing with google cloud storage and seems that content is uploaded twice using StreamWrapper.

    The test:

    use Gaufrette\Adapter\GoogleCloudStorage;
    use Gaufrette\Filesystem;
    use Gaufrette\StreamWrapper;
    require_once(__DIR__ . '/../vendor/autoload.php');
    const AUTH_FILE = './google-cloud.json';
    const BUCKET_NAME = 'testing';
    const LOCAL_FILE = __DIR__.'/test.txt';
    // Create filesystem
    $googleClient = new \Google_Client();
    $service = new \Google_Service_Storage($googleClient);
    $adapter = new class($service, BUCKET_NAME) extends GoogleCloudStorage
        public function write($key, $content)
            echo 'write strlen ' . strlen($content) . PHP_EOL;
            return parent::write($key, $content);
    $filesystem = new Filesystem($adapter);
    // Register wrapper
    $map = StreamWrapper::getFilesystemMap();
    $map->set(BUCKET_NAME, $filesystem);
    // Upload file
    copy(LOCAL_FILE, 'gaufrette://' . BUCKET_NAME . '/test.txt');

    The output is:

    [email protected]:~$ php ./test.php
    write strlen 0
    write strlen 5
    write strlen 5


    copy(LOCAL_FILE, 'gaufrette://' . BUCKET_NAME . '/test.txt');


    $filesystem->write('/test.txt', file_get_contents(LOCAL_FILE));

    The output is:

    [email protected]:~$ php ./test.php
    write strlen 5

    Is there a bug?

    opened by JoniJnm 0
  • v0.10.0(Oct 5, 2020)

  • v0.9.0(Dec 26, 2019)

    New features

    • Add MimeTypeProvider to AzureBlobStorage (#630)


    • Fix docker setup for dev env (#580)
    • Define env vars in .env file only (#615)
    • Add PHP Coding Standard check step on CI (#617)
    • PHPUnit tests enhancement (#627)

    Thank you @nicolasmure, @peter279k and @rgembalik for your contributions!

    Source code(tar.gz)
    Source code(zip)
  • v0.8.3(Jun 6, 2019)

  • v0.8.2(Jun 5, 2019)

    New features

    • Declare a FilesystemMapInterface (#604)
    • Add SizeCalculator support to GridFS (#603)
    • Local Adapter: directory deletion (#610)


    • GridFS : return empty array when object has no metadata (#609)

    Thank you @athos7933, @bsperduto and @nicolasmure for your contributions !

    Source code(tar.gz)
    Source code(zip)
  • v0.8.1(Jan 11, 2019)

  • v0.8.0(Dec 21, 2018)

    New features

    • Implement ChecksumCalculator interface for AzureBlobStorage adapter #594


    In #593 :

    • Drop support for EOL php versions (5.6 and 7.0)
    • Minimum requirement is now php 7.1
    • Add support for php 7.3


    • fix opencloud tests #579
    • fix appveyor build #589
    • Fix ini_get() for boolean values #595

    Thank you @andreybolonin, @damijank, @deguif and @nicolasmure for your contributions !

    Source code(tar.gz)
    Source code(zip)
  • v0.7.0(Sep 6, 2018)


    • FilesystemMap::set() should expects FilesystemInterface instead of Filesystem #576


    • Add PutObjectAcl in the required permission #566
    • Add php 7.2 to travis matrix #567
    • AWS3 docs fix #570
    • Ensure correct return type from Flysystem adapter "exists" method #572

    Thank you @andreybolonin, @clement-michelet, @jakob-stoeck, @nicolasmure, @teohhanhui, @tristanbes for your contributions !

    Source code(tar.gz)
    Source code(zip)
  • v0.6.0(Mar 26, 2018)

  • v0.5.0(Jan 5, 2018)

    New features

    • Added support for calculated size for Azure Blob Storage #523
    • GridFS Support for Metadata Retrieval after Write #535


    • Test case for AwsS3 now inherits common test case #514
    • Run azure tests on appveyor #512
    • Bump PHPUnit to ^5.6.8 #529
    • Use composer's autoload-dev #530
    • Drop HHVM support + sync docker conf with Travis #528
    • Refactoring tests to have more detailed failure messages #542


    • Documentation #510
    • Typos #506, #538
    • Fix incomplete tear down phase for AwsS3Test #516
    • Fix FTP tests + bug in PhpseclibSftp::fetchKeys() #527
    • fix travis build for php 5.6 #543
    • Quickfix for Adapter/AwsS3, check if count() call is allowed #544

    Thank you @andreasschacht, @bsperduto, @carusogabriel, @dawkaa, @gerkestam2, @GrahamCampbell, @Lctrs, @nicolasmure, @NiR- for your contributions !

    Source code(tar.gz)
    Source code(zip)
  • v0.4.0(Jun 17, 2017)

    • Following adapters have been deprecated: AclAwareAmazonS3, AmazonS3, Apc, Cache, LazyOpenCloud, Sftp, Dropbox, MogileFS, GoogleCloudStorage (see #482)
    • Improvement of test coverage during CI builds: functional tests for AzureBlobStorage, AwsS3, DoctrineDbal, Ftp, GridFS, OpenCloud and PhpseclibSftp now run on Travis (see #457, #460, #483, #484, #500, #504, #505)
    • Maintained adapters now have metapackage to enforce version of 3rd party libraries, and ease installation process (see #487)
    • Add FilesystemInterface and make current Filesystem implement it (see #492)
    • Drop support for PHP v5.4 and v5.5 (see #503)
    • File:
      • Add rename method to File (see #468)
    • Local adapter:
      • Suppress warning if directory has been created between check and create attempt (see #331)
      • Replace file_exists with is_file, to check if given path exists (see #479)
      • Allow Local adapter mkdir mode to cascade to it's Stream (see #488)
      • Fix phpdocs (see #489)
    • AzureBlobStorage:
      • Add support for multi container mode (see #486)
    • AwsS3 adapter:
      • Add ContentType support to AwsS3 (see #451)
      • Allow aws-sdk-php v2 and v3 to be used (see #457, #462, #475)
      • Provide mime type (see #491)
      • Deprecate AwsS3::getUrl() method, instead use ResolvableFilesystem from gaufrette/extras (see #496)
    • GridFS adapter:
      • Unmaintained mongo extension has been replaced with newer mongodb extension (see #460)
    • GoogleCloudStorage adapter:
      • Fixed missing leading "" before Google_Http_Request (see #471)
    • Ftp adapter:
      • Always ensure target directory exists before renaming (see #476)
      • Don't use FTP_USEPASSVADDRESS before php 5.6.18, and 7.0.0/7.0.1 (see #477, #480, #483)
    • Docs:
      • Add minimum IAM roles for AwsS3 adapter, and recommend to manually create bucket (see #467)

    Contributors: @NiR-, @nicolasmure, @WARrior-Alex, @zyphlar, @AntoineLelaisant, @Shivoham, @richardfullmer, @kcassam, @beebop1032, @dkarlovi.

    Also, we thank @edhgoose and @zyphlar who made patches for deprecated adapters, before those adapters were deprecated, but still did not see their respective work merged in this version.

    Source code(tar.gz)
    Source code(zip)
KNP Labs
Happy Awesome Developers
KNP Labs
Abstraction for local and remote filesystems

League\Flysystem About Flysystem Flysystem is a file storage library for PHP. It provides one interface to interact with many types of filesystems. Wh

The League of Extraordinary Packages 11.9k Jun 15, 2021
Abstraction for local and remote filesystems

League\Flysystem About Flysystem Flysystem is a file storage library for PHP. It provides one interface to interact with many types of filesystems. Wh

The League of Extraordinary Packages 11.9k Apr 22, 2021
An object oriented PHP driver for FFMpeg binary

php-ffmpeg An Object-Oriented library to convert video/audio files with FFmpeg / AVConv. Check another amazing repo: PHP FFMpeg extras, you will find

null 3.9k Jun 21, 2021
An object oriented PHP driver for FFMpeg binary

php-ffmpeg An Object-Oriented library to convert video/audio files with FFmpeg / AVConv. Check another amazing repo: PHP FFMpeg extras, you will find

null 3.9k Jun 17, 2021
☁️ Nextcloud server, a safe home for all your data

Nextcloud Server ☁ A safe home for all your data. Why is this so awesome? ?? ?? Access your Data You can store your files, contacts, calendars and mor

Nextcloud 14.4k Jun 21, 2021
The Hoa\Mime library.

Hoa is a modular, extensible and structured set of PHP libraries. Moreover, Hoa aims at being a bridge between industrial and research worlds. Hoa\Mim

Hoa 101 May 24, 2021
Apache MIME Types

Apache MIME Types Parses Apache MIME Types files and provides a simple interface to find extensions by type and type by extension. Features Bundles mi

dflydev 68 May 3, 2021
PHP-based anti-virus anti-trojan anti-malware solution.

What is phpMussel? An ideal solution for shared hosting environments, where it's often not possible to utilise or install conventional anti-virus prot

null 350 Jun 12, 2021
CSV data manipulation made easy in PHP

CSV Csv is a simple library to ease CSV parsing, writing and filtering in PHP. The goal of the library is to be powerful while remaining lightweight,

The League of Extraordinary Packages 2.8k Jun 12, 2021
PHP runtime & extensions header files for PhpStorm

phpstorm-stubs STUBS are normal, syntactically correct PHP files that contain function & class signatures, constant definitions, etc. for all built-in

JetBrains 1.1k Jun 9, 2021
Detects file type by filename or content and generates correct mimetype.

FileTypeDetector Files type detector based on file name extension or file content (binary content). Usage Installation Supported formats Usage File Ty

Sergey 22 Dec 27, 2020
🌩支持多家云存储的云盘系统 (A project helps you build your own cloud in minutes)

Cloudreve 支持多家云存储驱动的公有云文件系统. 演示站 • 讨论社区 • 文档 • 下载 • Telegram 群组 • 许可证 ✨ 特性 ☁️ 支持本机、从机、七牛、阿里云 OSS、腾讯云 COS、又拍云、OneDrive (包括世纪互联版) 作为存储端 ?? 上传/下载 支持客户端直传

Cloudreve 9k Jun 16, 2021
Analyze content to determine the appropriate Internet media type

Canal Content analysis for the purpose of determining Internet media types. Requirements PHP 5.3+ Installation Through Composer as dflydev/canal. Usag

dflydev 34 Feb 10, 2021