Weave Code
Media Library For Laravel Laravel Package
roundly-consulting/media-library-for-laravel
A Laravel media library for attaching files to Eloquent models. Upload and store images or documents, generate conversions and responsive thumbnails, organize media in collections, and manage custom properties through a clean, fluent API. Supports local and cloud disks for flexible media management.
A Laravel package for associating media files with Eloquent models. media-library-for-laravel provides a clean API for uploading, storing, and retrieving files, making it easy to manage images and documents alongside your application data.
- Attach media to Eloquent models through simple relationships
- Organize uploads into named collections
- Generate and store image conversions
- Use Laravel’s filesystem disks for local or cloud storage
- Retrieve URLs and metadata with a fluent API
Frequently asked questions about Media Library For Laravel
- How do I install the media library for Laravel?
- Install it with Composer using composer require roundly-consulting/media-library-for-laravel. Then publish and run the package migrations so the media table exists, and review the package configuration for disks and conversions. Check composer.json for the exact Laravel and PHP constraints before requiring it. Since 1.1.4 is a patch release, keep the version constraint aligned with your existing 1.1.x line unless you have tested the upgrade.
- Which Laravel and PHP versions does version 1.1.4 support?
- The authoritative constraints are in the package's composer.json; verify them against your runtime before scheduling the upgrade. Version 1.1.4 is a patch-level release in the 1.1.x line and does not introduce new configuration keys or schema changes according to the release notes. If you are coming from 1.0.x, treat the jump as a larger upgrade and run a full staging and concurrency test pass. Avoid assuming support from the major Laravel version alone.
- How do I attach an image or file to an Eloquent model?
- Use the package's attach() API from the model or media manager to associate an uploaded file with an Eloquent record. Media are polymorphic, so the same model can own media buckets and files can be attached to different model types. Wrap attach operations in a database transaction and handle ModelNotFoundException, because a shared media row can disappear before the locking read completes. The README shows the exact method names and fluent API for your version.
- Can I store media on multiple filesystem disks?
- Yes. The package supports multi-disk storage, so you can keep original files and conversions on different Laravel filesystem disks. Configure the disks in the package config and make sure the application's storage paths and visibility settings are correct for each disk. Same-disk copy operations participate in the package's transactional locking behavior; copying across disks follows normal filesystem semantics.
- How do conversions work, and can I generate image thumbnails?
- Conversions let you generate derivative files, such as thumbnails or resized images, from an uploaded original and retrieve them through the media API. Define the conversions your application needs and let the package store the generated files on the configured disk. Plan conversion generation around queue workers if image processing is slow, and remember that long transactions can delay deferred storage cleanup for force-deleted media.
- How do I organize media into collections?
- Collections let you group media within a model or bucket, so you can separate avatars, gallery images, documents, and other assets. Attach media to a named collection and retrieve that collection through the expressive API instead of filtering all media manually. Use collections together with polymorphic buckets when different model types need their own media spaces.
- Which database engines support the package's locking behavior?
- The correctness guarantees rely on a transactional RDBMS with row-level locking reads, such as MySQL InnoDB or PostgreSQL. SQLite and MyISAM-class engines do not honor those locking reads, so concurrency behavior can differ between local, CI, and production environments. Document the production engine requirement and run concurrency tests only against an engine that implements SELECT ... FOR UPDATE semantics.
- Why does attach() or copy() throw ModelNotFoundException?
- In 1.1.4, attach() and same-disk copy() can throw ModelNotFoundException when the shared media row disappears before the package acquires its lock. This is a race with deletion or another operation targeting the same media record, not necessarily an application bug. Callers should catch the exception explicitly and decide whether to retry, recreate the media, or return a validation-style error. Code that previously caught only filesystem exceptions needs updating.
- Does forceDelete() remove files from disk immediately?
- No. File deletion for forceDelete() is deferred until the surrounding transaction commits, so the database row and storage cleanup stay consistent if the transaction rolls back. That means code inspecting the disk immediately after forceDelete() may still see the file. In long transactions, plan for transient disk usage because previous bytes or deleted files are held until commit. Use afterCommit semantics or a queued cleanup job if downstream code depends on the file being gone.
- How should I handle deadlocks, lock timeouts, and orphaned files in production?
- Keep media operations inside short DB::transaction() blocks and catch database exceptions so lock timeouts and deadlocks can be retried at the application layer. High-concurrency imports, queue workers, and API uploads can serialize on hot media rows, so test those workloads against your production database engine. For orphaned files in the window between commit and deferred deletion, build a scheduled reconciliation job that compares media rows with disk contents; the provided notes do not document a built-in reconciliation command. Read media state from the primary when correctness matters, because replicas can still serve stale rows.
Weaver
How can I help you explore Laravel packages today?