Weave Code
Gaufrette Laravel Package
knplabs/gaufrette
Gaufrette is a PHP filesystem abstraction layer that lets your app read and write files without knowing where they're stored, so you can switch between local storage, Amazon S3, FTP, and other adapters without changing your code.
PHP library that provides a filesystem abstraction layer − will be a feast for your files!
Frequently asked questions about Gaufrette
- Is Gaufrette a good fit for a Laravel application?
- Laravel already ships a filesystem abstraction, Illuminate\Filesystem\FilesystemManager over Flysystem v3, exposed through the Storage facade and filesystems.disks. Adding Gaufrette therefore introduces a competing second abstraction rather than a new layer. It is justified only when a specific adapter covers a backend Laravel's disk lineup handles poorly, such as GridFS, Doctrine DBAL, Zip or OpenCloud, and only for a bounded subsystem like media ingestion, legacy migration or archival bundles. It should never become your default storage path.
- How do I install Gaufrette in a Laravel project with Composer?
- Run composer require knplabs/gaufrette plus the adapter metapackage you need, for example gaufrette/aws-s3-adapter, since each metapackage pulls its own third-party dependencies. Then bind a Gaufrette\Filesystem singleton in a service provider and inject it where required. There is no Laravel bundle available, so you own all the glue code; type-hint the adapter interface or Filesystem rather than reaching for a facade.
- Does Gaufrette integrate with Laravel's Storage facade and filesystems.php disks?
- No. Gaufrette is independent of Laravel's disk configuration, so it does not read filesystems.disks, does not participate in php artisan storage:link, and does not give you Storage::url(), temporaryUrl() signed URLs, visibility semantics, or the Storage::fake() testing pattern. Files written through it are effectively invisible to framework conventions. Any consumer that assumes Storage semantics needs custom work.
- Which Gaufrette adapters cover backends Laravel disks do not?
- The genuinely useful cases are GridFS, Doctrine DBAL, Zip, OpenCloud and some SFTP/FTP variants. If your backend is local storage, Amazon S3, Azure Blob Storage, Google Cloud Storage or plain FTP, Laravel's disks already cover it and Gaufrette adds no value. Note that Gaufrette's Flysystem adapter runs Flysystem as a Gaufrette backend, which is the opposite direction from what a Laravel application would need.
- Which PHP and Laravel versions does Gaufrette support?
- Read the composer.json of knplabs/gaufrette and of each adapter metapackage rather than the README, whose development docs still describe a PHP 7.1 to 7.3 Docker matrix. Laravel 10 and 11 require PHP 8.1 or 8.2, so verify the actual constraint lines against your baseline before committing. Support varies by adapter because each metapackage carries its own dependency requirements.
- Why does Gaufrette have no stable 1.0 release, and what is the upgrade risk?
- The README explicitly states the project does not have any stable release yet, despite a published changelog and a deprecation schedule. The legacy AmazonS3 and AclAwareAmazonS3 adapters have been deprecated since 0.4.0 and are slated for removal in 1.0.0, so assume a breaking removal is on the roadmap. Pin versions and set a re-evaluation checkpoint before relying on it in production.
- How do I test Gaufrette code in Laravel without hitting real storage?
- Use the InMemory adapter, or Local pointed at a temporary directory, and inject the adapter so tests can substitute it. Gaufrette does not hook into Storage::fake(), and Laravel's assertExists helpers do not apply to it. Keeping Gaufrette-bound code behind a small interface of your own keeps fakes and test setup simple.
- Can I use a Gaufrette adapter as a custom Laravel disk driver via Storage::extend?
- Storage::extend lets you register a custom driver, and wrapping a Gaufrette adapter inside one is technically possible. In practice you then reimplement URL generation, MIME type and size resolution, streaming reads and visibility semantics yourself. That cost usually exceeds the value of the adapter that motivated the change unless it does something Laravel genuinely cannot.
- How does Gaufrette handle exceptions compared with Flysystem?
- Gaufrette failures surface as adapter-specific exceptions and are not mapped to Flysystem's UnableToReadFile and UnableToWriteFile hierarchy. Error handling therefore becomes per-adapter and diverges from the rest of a Laravel application. If you mix Gaufrette with Storage, expect two error models and wrap Gaufrette calls in your own exception layer.
- What are the alternatives to Gaufrette in Laravel, and who maintains the adapters?
- The native option is Laravel's Flysystem-backed disks, optionally with league/flysystem adapters installed directly when you need an extra backend. Gaufrette remains reasonable for legacy Symfony-style code or its unique adapters. Maintenance is split across named individual maintainers per adapter, so bus factor varies by backend, and only InMemory, Local and Zip are collectively maintained.
Weaver
How can I help you explore Laravel packages today?