kphoen/gaufrette-extras
Extra adapters and utilities for the Gaufrette filesystem abstraction library. Extends Gaufrette with additional storage backends and helpers, letting PHP applications manage local and remote files through a consistent interface with less boilerplate.
Install alongside Gaufrette (the package is a set of decorators, not a standalone filesystem):
composer require kphoen/gaufrette-extras
Check what Gaufrette version constraint Composer resolves — the package dates from 2015 and targets the 0.2/0.3 era API, so expect to pin gaufrette/gaufrette accordingly.
Read the README and src/ first. The library is small (a handful of classes), so the fastest path is to skim the resolver interface and the filesystem decorator rather than looking for docs. There is no official documentation site and no Laravel/Symfony bundle.
Identify the one problem it solves: generating a public URL for a file held in a Gaufrette filesystem. Gaufrette gives you read/write/has, but not "where do I point a browser at this?" — this package fills that gap by decorating a Filesystem with a resolver.
Minimal first use case:
use Gaufrette\Filesystem;
use Gaufrette\Adapter\Local;
use Gaufrette\Extras\ResolvableFilesystem;
use Gaufrette\Extras\Resolvable\Resolver\LocalResolver;
$adapter = new Local('/var/www/app/storage/uploads');
$filesystem = new ResolvableFilesystem(
new Filesystem($adapter),
new LocalResolver('/uploads') // public base URL
);
$filesystem->write('avatars/42.png', $binary);
echo $filesystem->resolve('avatars/42.png'); // /uploads/avatars/42.png
That decorator is the package's reason to exist — everything else is supporting glue.
If you're on Laravel, wrap that construction in a small service provider and bind ResolvableFilesystem (or an app-specific interface) into the container. Don't try to swap Laravel's Storage facade for it unless you specifically need a Gaufrette adapter (FTP, GridFS, custom S3 layout) that Laravel doesn't ship.
Decorator-over-existing-filesystem. The idiomatic pattern is to keep your existing Gaufrette Filesystem for reads/writes and wrap it only where URLs are needed:
$base = new Filesystem($adapter); // used elsewhere
$resolvable = new ResolvableFilesystem($base, $resolver);
Because it decorates rather than replaces, you can register both in the container and inject the plain Filesystem for I/O and the resolvable one for view/URL concerns.
Resolver-per-backend. Keep URL construction out of your domain code by giving each storage backend its own resolver. A LocalResolver with a public base path in dev; a bucket/CDN-aware resolver in production. The ResolverInterface is the seam to implement if the package's built-in resolvers don't cover your backend (e.g. a custom signed-URL generator):
class SignedS3Resolver implements ResolverInterface
{
public function resolve($path) { /* return pre-signed URL */ }
}
Chain / fallback resolvers. For multi-bucket or multi-drive setups, compose resolvers: try the primary, fall back to a read-only archive resolver. This keeps "where does this file live?" logic in one place instead of scattered if statements.
Presenter / Twig / Blade integration. Never expose raw paths. Resolve at the rendering boundary — a Blade directive, a small present() method on a view model, or a dedicated transformer — so the filesystem remains a data concern:
// Blade: {{ $url->forPath($user->avatar_path) }}
Config-driven wiring. Put base URLs, bucket names, and CDN hosts in config, not in resolver constructors scattered through the app. In Laravel this is a config/filesystems.php-style entry plus a singleton binding; in plain PHP it's a small factory.
Testing. Use Gaufrette's in-memory/local adapter in tests and a fake resolver that returns deterministic URLs (https://cdn.test/{path}). This lets you assert URL generation without touching real storage, and avoids the common trap of tests that "pass" because the file happens to exist on the dev machine.
^8.x) and modern Gaufrette. You may need to fork with updated composer.json constraints, or drop the package and copy the two or three classes you actually use into your app — often the sanest choice for something this small.Filesystem, Adapter, and metadata signatures changed across Gaufrette 0.2 → 0.9. A decorator written against 0.2 can silently break (or fatal) on newer versions. Verify the resolved Gaufrette version and run the package's own test suite against it.resolve() does not check existence. It builds a URL from a key; it won't tell you the file is missing. Pair it with $filesystem->has($path) (or catch FileNotFound) at the boundary where you build the URL, otherwise you'll emit dead links.public/, the URL will 404 — either symlink, serve via a controller, or use a signed resolver instead.avatars/42-v3.png) rather than expecting the resolver to handle it....var_dump/dd on the resolvable instance is noisy. When something misbehaves, test the resolver in isolation ($resolver->resolve('foo/bar.txt')) before suspecting the filesystem.ResolverInterface is the intended customization seam. If you need signed URLs, CDN host rewriting, or per-tenant buckets, implement it rather than subclassing the filesystem — that keeps you compatible if you later replace the package.Storage::url() already covers this. Reach for Gaufrette + these extras only when you're already committed to a Gaufrette adapter Laravel lacks (FTP, GridFS, a legacy S3 layout), or when maintaining an older codebase that already depends on it.How can I help you explore Laravel packages today?