Weave Code
Laravel Medialibrary Laravel Package
spatie/laravel-medialibrary
Associate files with Eloquent models via a simple API: add uploads or local paths to media collections, store them on any Laravel filesystem, and generate image manipulations for images and PDFs. Ideal for managing media in Laravel apps.
Associate files with Eloquent models
Frequently asked questions about Laravel Medialibrary
- What is spatie/laravel-medialibrary used for in Laravel?
- It associates files with Eloquent models through polymorphic media records, so you can attach uploads, images, PDFs, or downloads to models like User, Product, or Article. Files are organized into named collections and stored on any Laravel filesystem disk. It also handles image and PDF conversions plus responsive image variants.
- How do I install spatie/laravel-medialibrary in a Laravel app?
- Install it with Composer using composer require spatie/laravel-medialibrary, then publish the migrations and config and run php artisan migrate. Add the HasMedia interface and InteractsWithMedia trait to each Eloquent model that should own files. The package documentation lists the exact vendor:publish tags and setup steps.
- Which Laravel versions does spatie/laravel-medialibrary support?
- As of v11.x, the package works with Laravel 10 through 13, and older Laravel versions are supported through older branches. Always check the Composer constraints for the exact release you plan to use. Upgrading major versions may require following the package upgrade guide.
- Can I store media on S3 and local disk at the same time?
- Yes. Each media collection can specify its own disk, so you can keep small files on local storage and large files on S3. Because storage uses Laravel's filesystem, any configured disk such as local, S3, GCS, or Azure Blob can be used.
- How do image conversions and thumbnails work in laravel-medialibrary?
- You define conversions on your media model or through media conversion registration, and the package generates derivative files such as thumbnails or resized images. It can use GD, Imagick, Vips, or FFmpeg depending on your configuration. Conversions also work for PDFs, not just images.
- Does spatie/laravel-medialibrary support responsive images?
- Yes. It can generate optimized variants such as image-200x200.jpg and output responsive image tags with source elements, including WebP variants. This helps frontend frameworks and browsers load appropriately sized media. You control the generated sizes and naming rules through your conversion definitions.
- How should I test media uploads and conversions with Pest or PHPUnit?
- The package is Pest and PHPUnit ready and is tested in CI with GitHub Actions. In your own tests, use Laravel's fake storage disks to avoid hitting S3 or other remote backends. Assert that media records land in the expected collection and that conversion files are generated as expected.
- Is spatie/laravel-medialibrary suitable for high-volume production apps?
- It can work at scale, but it stores metadata in a media table that may grow large, so index columns like model_type, model_id, and collection_name and tune queries or caching. Very large libraries, such as 10M+ files, may strain database queries or filesystem operations and need load testing. For simple single-file uploads, Laravel's native file handling may be enough.
- What are alternatives to spatie/laravel-medialibrary?
- For simple cases, Laravel's native file uploads and HasFile-style traits can cover a single avatar or attachment field. Intervention/image is an option when you only need image manipulation, while custom storage tables may fit highly specialized legacy systems. Medialibrary is heavier but adds collections, multi-disk storage, conversions, and responsive images.
- How do I migrate existing uploads to spatie/laravel-medialibrary?
- Moving from direct S3 uploads or custom file tables usually requires refactoring and a backfill script that adds existing files into media collections. Pilot the integration on a non-critical model such as BlogPost and test your target storage backends for edge cases like S3 path encoding. Also plan for file retention and deletion requirements such as GDPR erasure.
Weaver
How can I help you explore Laravel packages today?