Weave Code
Laravel Attachments Laravel Package
aniftyco/laravel-attachments
Attach files to any Eloquent model in Laravel with a clean, expressive API. laravel-attachments stores attachments polymorphically with file metadata, so any model can own images, documents, or other files on any storage disk—no boilerplate or custom migrations required.
Turn any field on your Eloquent models into attachments with automatic file management, validation, and cleanup.
Frequently asked questions about Laravel Attachments
- What does aniftyco/laravel-attachments do?
- It adds a trait that turns an attribute on an Eloquent model into a managed file attachment, handling storage, validation, metadata, and cleanup. Attachments are stored polymorphically, so any model can own images, documents, or other files without custom migrations or boilerplate. It is aimed at simple, one-file-per-field use cases such as avatars, logos, and policy PDFs rather than full digital asset management.
- How do I install and configure laravel-attachments?
- Install it with composer require aniftyco/laravel-attachments, then add the package trait to the models that should own files and declare which attributes are attachments. The happy path is short: define validation rules for the field, point it at a storage disk, and start saving uploads through the model. Expect to spend the real integration time on edge cases like soft deletes, bulk operations, transactions, and queue failures rather than on the initial setup.
- Which Laravel and PHP versions does laravel-attachments support?
- The available package context does not publish a supported Laravel or PHP version matrix, so verify it directly before committing. Check the composer.json require constraints on the repository and the matching release on Packagist, then confirm against your application's framework version. Because adoption is very low, older framework versions are unlikely to be exercised by other users, so test your exact combination in a spike.
- Can I store attachments on S3 or a custom filesystem disk?
- Yes, the package is designed to place attachments on any Laravel storage disk, including S3 and local disks, using the framework's filesystem abstraction. That keeps you free of vendor lock-in at the API surface: the license is MIT and there is no external service dependency. Confirm how disks are resolved per attribute and whether URLs are generated for private versus public disks before you rely on it.
- Does laravel-attachments support multiple files per field or file collections?
- The package is built around simple one-file-per-field semantics, which covers avatars, logos, supporting documents, and similar CRUD-shaped attributes. Its fit degrades for multi-file collections, ordering, renditions or thumbnails, and per-file metadata, where a dedicated media library is a better match. If you need galleries or versioned files, prototype that requirement early rather than assuming the trait scales to it.
- How does automatic file cleanup work when a model is deleted or updated?
- Cleanup is driven by model lifecycle events, so replacing or removing an attachment triggers deletion of the underlying stored file. The important caveat is that Eloquent events do not fire for Model::where(...)->delete(), truncate(), raw SQL, or foreign key cascades, so those paths can leave orphaned objects and unexplained storage spend. File writes and database commits are also two systems without a shared transaction, so verify whether cleanup defers to afterCommit and how it behaves when a transaction rolls back or a queued job retries.
- How does laravel-attachments handle validation and upload security?
- The package supports validation rules on attachment fields, but convenience packages are exactly where insecure defaults tend to hide, so treat security as your responsibility to verify. Check MIME sniffing versus extension trust, SVG and HTML polyglot uploads, path traversal in generated storage keys, and whether public disk URLs expose files you intended to keep private. It manages bytes, not content lifecycle, so virus scanning, PII classification, legal hold, and retention policy must be designed around it rather than delegated to it.
- Is laravel-attachments production ready?
- Treat it as an unvetted internal utility rather than a dependency for a revenue-critical surface. It has roughly 13 stars and a single-maintainer agency behind it, which means almost no downstream usage to shake out edge cases, no community corpus to lean on, and a bus factor of effectively one. The architecture is idiomatic Laravel and cheap to trial, but adoption should follow a time-boxed spike with a documented exit path, since falling back to a small custom trait is a code-level cost rather than a contractual one.
- How do I test attachments with laravel-attachments in my Laravel test suite?
- Use Storage::fake() for the disk your attachment field targets and UploadedFile::fake() to generate uploads, then assert the file exists with Storage::disk(...)->assertExists(). Cover the failure modes too: validation rejection, replacement of an existing file, deletion on model removal, and behavior under soft deletes. Explicitly test bulk deletes and raw query deletes, because event-driven cleanup will not run there and you want that leak visible in tests rather than in your S3 bill.
- What are alternatives to laravel-attachments?
- spatie/laravel-medialibrary is the mature choice when you need collections, conversions, ordering, and per-file metadata, at the cost of more configuration and its own migrations. For a single managed field, a small custom trait or cast built on the Storage facade plus an UploadedFile validation rule is often all you need and keeps full ownership of cleanup semantics. Intervention Image or a queue-based pipeline handles renditions if thumbnails are the only gap in the simpler options.
Weaver
How can I help you explore Laravel packages today?