Weave Code
Media Library Laravel Package
artisanpack-ui/media-library
A Laravel media library for handling uploads, storage, and image conversions, with a UI-friendly API for attaching and managing files across your application.
artisanpack-ui/media-library is a Laravel package that adds a ready-made media management interface to your application, letting you upload, browse, and organize files without building an admin UI from scratch. It pairs a clean, responsive Blade + Livewire front end with straightforward configuration, so images and documents can be attached to your Eloquent models in minutes.
- Drag-and-drop uploads with validation and automatic storage handling
- Searchable media grid with thumbnails, filters, and bulk actions
- Eloquent attachments via simple trait and relationship helpers
- Configurable storage disks for local or cloud drivers
- Publishable views and config for full customization
Frequently asked questions about Media Library
- How do I install artisanpack-ui/media-library in a Laravel application?
- Install the package with Composer using composer require artisanpack-ui/media-library, then follow the package setup steps for configuration and migrations. Check whether the package migrations are auto-loaded or need to be published before running php artisan migrate. Confirm your Laravel and PHP versions match the supported matrix, and make sure queue workers are available if you plan to use queued media listeners.
- How do I associate uploaded media with Eloquent models using this Laravel media library?
- The package provides a simple API to associate media records with Eloquent models, so you can attach assets to products, posts, users, or other application entities. Uploads can flow through helper, trait, Livewire, or HTTP entry points that share the same media handling path. This keeps model associations consistent regardless of where the upload originates in your application or admin UI.
- Which Laravel, PHP, and database versions does artisanpack-ui/media-library support?
- The package is built for Laravel applications and v1.5.0 uses standard Laravel package patterns, but you should verify the exact Laravel and PHP version matrix in the repository before upgrading. Database support needs checking across MySQL, PostgreSQL, and SQLite, especially for new media columns, indexes, nullability, defaults, and JSON or format-column behavior. Test migrations against your production database engine rather than assuming parity across all three.
- Does artisanpack-ui/media-library support Laravel queues for media uploads?
- Yes, v1.5.0 adds a queueable MediaUploaded event that lets you subscribe ShouldQueue listeners without forcing synchronous work into the upload request. This is useful for downstream enrichment such as AI alt-text generation because it decouples that work from the upload lifecycle. Teams without queue workers can still use the package, but the main benefit of the event is reduced until workers are running.
- How do I avoid duplicate AI alt-text generation when upgrading to the MediaUploaded event?
- If you already listen to ap.mediaLibrary.uploaded for AI alt-text, migrate that listener to MediaUploaded or disable the old one before enabling the new queued workflow. The event fires from every upload entry point, so running both listeners can create duplicate downstream work. Make listeners idempotent because queue retries could otherwise generate duplicate alt text or duplicate records.
- How does optimization status tracking work in artisanpack-ui/media-library?
- The package denormalizes pipeline state onto the media table using fields such as optimization_status, byte counts, formats, and error text, which helps power UI badges and reporting. Treat those fields as a schema-level public API because consumers may depend on their values and meaning. Verify status transitions are atomic under concurrent processing, and confirm how partial format generation is represented.
- Is the media:backfill-optimization-status command safe for large media libraries?
- The backfill command marks existing image rows as optimized, which is useful for legacy libraries but is an operational step rather than just a code upgrade. Before running it on production, check whether the command is chunked, resumable, rate-limited, and able to target date ranges or specific media IDs. Run it on a copy first because an incomplete or incorrect backfill can misrepresent historical optimization state.
- Can upgrading to v1.5.0 lock or pressure a large media table?
- Version 1.5.0 adds six new columns to the media table, so large libraries may see migration locking or write pressure depending on the database engine. Review whether the migrations are additive and safely reversible, and confirm the new columns are nullable, defaulted, and indexed as expected. Plan the migration and backfill as separate operational steps with batching and monitoring.
- Can I use artisanpack-ui/media-library with Livewire or the package HTTP upload path?
- Yes, the package uses a shared upload path across helper, trait, Livewire, and HTTP entry points, so media handling stays consistent across integration styles. The MediaUploaded event fires from every upload entry point, which means downstream listeners may run for Livewire and HTTP uploads alike. Test failure UX carefully because image processing can set failed status on exception while still surfacing the exception after the media record already exists.
- How should I handle failed image optimization or upload errors in this Laravel media package?
- The processImage method sets failed status on exception but still surfaces the exception, which is correct for observability but can show upload failure after a media record has been created. Design your UI and listeners to handle that partial-success state rather than assuming a failed response means no media row exists. Also consider whether optimization_status captures partial format generation, because a single status field may not reflect every generated variant.
Weaver
How can I help you explore Laravel packages today?