Weave Code
Filesystem Laravel Package
zenstruck/filesystem
Zenstruck Filesystem is a Symfony bundle for attaching files and images to Doctrine entities. It handles storage via Flysystem adapters, image transformations, metadata, and automatic orphan cleanup, keeping file management clean and testable.
Wrapper for league/flysystem with alternate API and added functionality.
Frequently asked questions about Filesystem
- Does zenstruck/filesystem work with Laravel?
- No. Zenstruck Filesystem is a Symfony bundle registered through the Symfony kernel and dependency injection container, and its persistence model is built on Doctrine ORM mappings and Doctrine lifecycle event subscribers. Laravel's default Eloquent ORM has no lifecycle integration with the bundle, so direct use is not practical. If your stack is Laravel-first, evaluate it as a design reference rather than a dependency.
- Can I use zenstruck/filesystem with Eloquent models instead of Doctrine entities?
- Not without significant custom work. The package stores file and image metadata as Doctrine-mapped properties and relies on Doctrine listeners to move pending uploads and delete files on entity removal. Eloquent has no equivalent hook into that pipeline, so you would need to reimplement the lifecycle handling yourself. At that point you are porting the pattern, not using the package.
- How do I install and configure zenstruck/filesystem?
- You install it with Composer and register the bundle in your Symfony bundles configuration, then define Flysystem storage adapters (local disk, S3, and so on) as services. File and Image properties on your Doctrine entities are mapped with the bundle's mapping types, and Symfony form types are provided for upload fields. Configuration lives in your Symfony config files, not in a Laravel config directory.
- What Laravel package should I use instead for attaching files to models?
- Spatie's laravel-medialibrary is the most common Eloquent-native choice for attaching files and images to models with conversions and disk configuration. For simpler needs, Laravel's Storage facade plus a custom Eloquent cast and model observers covers most of the same ground. Both options stay inside idiomatic Laravel and avoid standing up Doctrine as a parallel persistence layer.
- Is zenstruck/filesystem safe to depend on in production?
- It is MIT licensed, which removes legal lock-in, but the ecosystem is small and the release history is essentially single-track, implying a bus factor of roughly one. File persistence is business-critical, so a single-maintainer dependency carries real operational risk. Pin the version, track Symfony, Doctrine, and Flysystem upgrade windows, and have a fallback plan for reconciliation if maintenance stalls.
- Does zenstruck/filesystem support S3 and other Flysystem adapters?
- Yes. Storage is delegated to Flysystem adapters, so local disk, S3, and other Flysystem-compatible backends are supported through configuration. You choose the adapter per file class or storage definition. Note that Flysystem major version migrations are one of the breaking windows to track when pinning the package.
- How does zenstruck/filesystem handle orphaned file cleanup?
- Cleanup relies on Doctrine lifecycle events firing during normal entity persist, update, and remove operations. Bulk DQL deletes, raw SQL, and queue workers that bypass the ORM will silently leak files because the listeners never run. If you depend on automatic orphan removal in production, audit every deletion path in your codebase for ORM bypasses and plan a reconciliation process.
- Does zenstruck/filesystem handle image resizing and filters on its own?
- No. Image filtering and resizing are delegated to LiipImagineBundle, which makes your image pipeline risk transitive on a third bundle. You need to install and configure that bundle alongside Zenstruck Filesystem to get transformations. If you are evaluating dependency surface area, count both packages together.
- How would I port the zenstruck/filesystem pattern to a Laravel app?
- Adopt the design rather than the package: create a StoredFile value object, persist it with an Eloquent custom cast, and route writes through a service backed by Laravel's Storage facade, which is already Flysystem-based. Add a scheduled files:prune-orphans command or queued job for reconciliation, since Eloquent has no equivalent of Doctrine lifecycle listeners. Target parity on persist, replace, delete, and orphan sweep, and backfill legacy uploads with a one-time migration into the new schema.
- Which Symfony and Doctrine versions does zenstruck/filesystem support?
- The package tracks Symfony releases as a bundle and targets Doctrine ORM, so Symfony major bumps and the Doctrine ORM 2 to 3 transition each represent potential breaking windows. There is no Laravel version support because it is not a Laravel package. Check the composer.json constraints for the exact supported ranges before adopting and pin accordingly.
Weaver
How can I help you explore Laravel packages today?