rato-guras/media-library

Reusable Laravel media library extracted from production app workflows.

v1.0.0 2026-03-24 15:28 UTC

Requires

• php: ^8.1
• illuminate/console: ^10.0|^11.0|^12.0
• illuminate/database: ^10.0|^11.0|^12.0
• illuminate/filesystem: ^10.0|^11.0|^12.0
• illuminate/http: ^10.0|^11.0|^12.0
• illuminate/routing: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0
• illuminate/view: ^10.0|^11.0|^12.0
• intervention/image: ^3.9

MIT

• media
• laravel
• uploads
• picker
• media-library

README

A standalone, reusable Laravel media library package with upload, browser, picker, thumbnail, and model-attachment support.

Requirements

• PHP: ^8.1
• Laravel: 10.x, 11.x, 12.x
• Intervention Image: ^3.9

Installation

composer require rato-guras/media-library
php artisan media-library:install
php artisan migrate

Features

• Upload image, document, audio, video, and generic files
• Optional image optimization pipeline (WebP conversion)
• Thumbnail generation for images
• Folder-aware media organization
• Media browser/grid endpoints and Blade UI
• Reusable Blade media picker component
• URL import endpoint
• Soft delete + restore + force delete behavior
• Polymorphic model attachment via HasMedia

Auto Discovery

The package is auto-discovered by Laravel via composer.json:

• Provider: RatoGuras\\MediaLibrary\\MediaLibraryServiceProvider
• Facade alias: MediaLibrary

Configuration

Publish config with install command or manually:

php artisan vendor:publish --tag=media-library-config

Config file: config/media-library.php

Key options:

• disk
• route_prefix
• route_middleware
• upload_directory
• image_directory
• thumbnail_directory
• document_directory
• audio_directory
• video_directory
• file_directory
• max_file_size
• allowed_mime_types
• image_driver
• create_thumbnails
• thumbnail_width
• thumbnail_height
• convert_images_to_webp

Routes

All routes are prefixed by config('media-library.route_prefix') and use middleware from config('media-library.route_middleware').

Named routes:

• media-library.index
• media-library.grid
• media-library.picker
• media-library.upload
• media-library.upload-from-url
• media-library.folder.create
• media-library.folder.delete
• media-library.delete-by-collection
• media-library.move
• media-library.restore
• media-library.update
• media-library.destroy

Blade Component

Default alias: <x-media-picker />

Example:

<x-media-picker
    modalId="post-cover-picker"
    title="Select or Upload Cover"
    :allowMultiple="false"
    :allowUpload="true"
    :allowView="true"
    triggerSelector=".open-media-picker"
    onSelect="onCoverSelected"
    inputTarget="#cover_media_id"
    collection="cover"
/>

Model Attachment

Use the trait:

use Illuminate\Database\Eloquent\Model;
use RatoGuras\MediaLibrary\Traits\HasMedia;

class Post extends Model
{
    use HasMedia;
}

Usage:

$post->attachMediaFromRequest('cover_image', ['collection' => 'cover']);
$all = $post->getMedia('cover');
$first = $post->getFirstMedia('cover');
$post->deleteMedia($mediaId);
$post->clearMedia('cover');

Image Driver Fallback

• Set media-library.image_driver=imagick to prefer Imagick.
• If Imagick is unavailable, the package automatically falls back to GD.
• Default driver is GD for broad compatibility (including Windows).