README

A comprehensive media management package for Laravel applications with support for image processing, folder organization, tagging, and modern image format conversion (WebP/AVIF).

Features

Core Features

📁 Hierarchical Folder Organization - Organize media into nested folders
🏷️ Tag Management - Tag media items for easy categorization
🖼️ Image Processing - Automatic thumbnail generation in multiple sizes
🚀 Modern Image Formats - Automatic conversion to WebP and AVIF
📦 Storage Abstraction - Support for multiple storage backends via Laravel's filesystem
🎬 Video Support - Video thumbnail extraction using FFmpeg (optional)
🔍 Advanced Search & Filtering - Search by name, filter by type, folder, or tag
🎯 Drag & Drop Upload - Modern upload interface with progress tracking
🖱️ Media Modal Component - Single/multi-select modal for choosing media with context support
🔐 Permission-based Access Control - Granular capability-based permissions
🎨 Publishable Views - Customize all Blade views to match your design
🧪 Comprehensive Test Coverage - Over 500 tests with 90%+ coverage

New in v1.1

⚡ Livewire 4 Streaming Uploads - Real-time upload progress with wire:stream (automatic fallback for Livewire 3)
📊 Media Statistics Dashboard - KPI cards with sparklines showing upload trends, storage usage, and type distribution
📤 Table Export - Export media library data to CSV, XLSX, or PDF formats
🪟 Glass Effects - Modern glassmorphism UI with customizable blur and transparency
🧩 Visual Editor Integration - MediaPicker component for CMS visual editors with block content helpers
⌨️ Keyboard Navigation - Full keyboard support for media selection (arrow keys, Enter, Escape)
🕐 Recently Used Media - Quick access to recently selected media items
⚙️ Feature Flags - Granular control over features via configuration

Requirements

PHP 8.2 or higher (PHP 8.3+ required when using Laravel 13)
Laravel 12.0 or 13.0
Intervention Image 3.0 for image processing
FFmpeg (optional, for video thumbnail extraction)

Installation

Install via Composer:

composer require artisanpack-ui/media-library

Quick Start

// Upload media
$media = apUploadMedia($file, [
    'title' => 'My Image',
    'alt_text' => 'Alt text for accessibility',
    'folder_id' => 1,
]);

// Get media URL
$url = apGetMediaUrl($mediaId, 'thumbnail');

// Display image
$media = apGetMedia($mediaId);
echo $media->displayImage('large', ['class' => 'img-fluid']);

What's New in v1.1

Livewire 4 Streaming Uploads

Real-time upload progress with automatic Livewire 3 fallback:

<livewire:media-upload-zone wire:stream="uploadProgress" />

Visual Editor Integration

Embed the MediaPicker in your CMS visual editor:

<livewire:media-picker
    context="featured-image"
    :allowed-types="['image']"
    :multi-select="false"
/>

Media Statistics Dashboard

Display KPI cards with sparklines:

<livewire:media-statistics
    :show-sparklines="true"
    :sparkline-days="30"
/>

Table Export

Export your media library to various formats:

<x-artisanpack-table-export
    :formats="['csv', 'xlsx', 'pdf']"
    filename="media-export"
/>

AI features

Media Library integrates with artisanpack-ui/ai to offer three vision-powered helpers for image media items. Each feature is toggled through the ai package's feature registry (config('artisanpack.ai.features.*') or the AI settings admin surface).

Feature key	Agent	What it does
`ai.alt_text`	`ArtisanPackUI\Ai\Agents\AltTextGenerationAgent` (ships in `artisanpack-ui/ai`)	Suggests accessibility-friendly alt text for an image.
`media.suggest_tags`	`ArtisanPackUI\MediaLibrary\Ai\Agents\ImageTagSuggestionAgent`	Picks matching tags from the existing `media_tags` taxonomy (opt-in new tags).
`media.image_description`	`ArtisanPackUI\MediaLibrary\Ai\Agents\ImageDescriptionAgent`	Produces a paragraph-length image description for galleries, portfolios, etc.

Surfaces

Livewire — the <livewire:media::media-edit> and <livewire:media::media-upload> components gain "AI suggest" buttons next to the alt-text, description, and tag fields. Buttons hide themselves when the feature is disabled or artisanpack-ui/ai is absent.
React — the shipped MediaEdit.tsx component wires "Suggest with AI" and "Describe with AI" buttons around the alt-text, description, and tag fields. resources/js/react/utils/api.ts exports typed helpers (suggestMediaAltText, suggestMediaTags, suggestMediaDescription). AI is post-upload only in React/Vue because the JSON endpoints require a persisted media item — the Livewire MediaUpload supports pre-upload suggestions by handing the AI agent a TemporaryUploadedFile directly.
Vue — the shipped MediaEdit.vue component mirrors the React wiring. The same helpers are exported from resources/js/vue/utils/api.ts.
Any HTTP client — all three features are exposed as JSON endpoints under the existing api/media prefix. Roll your own client if you're not using our React/Vue components:
```
POST /api/media/{id}/ai/alt-text                       -> { data: { alt_text, confidence, warnings } }
POST /api/media/{id}/ai/tags       { allow_new: bool } -> { data: { tags[], new_tags[], confidence } }
POST /api/media/{id}/ai/description { length: "short" | "medium" | "long" } -> { data: { description, confidence, warnings } }
```
Each endpoint enforces the update policy on the media item and returns 403 when the feature is disabled, 422 when the target media isn't an image, and 503 when no AI credentials are configured.

Enabling the features

artisanpack-ui/ai is a required dependency starting in v1.3. Configure credentials via config/artisanpack.php or the "AI → Settings" admin page and toggle individual features from "AI → Features".

Documentation

📚 Complete Documentation

Getting Started

Quick Start - Get up and running quickly
Installation - Detailed installation instructions
Configuration - All configuration options
Upgrading to v1.1 - Migration guide from v1.0.x

Usage

Helper Functions - Common usage patterns
Working with Models - Advanced model usage
Livewire Components - UI component guide
Streaming Uploads - Livewire 4 real-time upload progress
Table Export - Export media data to CSV/XLSX/PDF
AI Features - Alt text, tag suggestions, image descriptions (v1.3)

Visual Editor Integration

MediaPicker Component - Visual editor media selection
Block Content Helpers - Block content integration
Integration Examples - Complete integration examples

Dashboard & Statistics

Media Statistics - KPI cards and sparklines
Glass Effects - Glassmorphism UI customization

API & Integration

API Reference - Complete API documentation
CMS Integration - Digital Shopfront CMS setup
Permissions - Access control guide
Customization - Customization options

Reference

Troubleshooting - Common issues and solutions
FAQ - Frequently asked questions
Changelog - Version history

Testing

Run the test suite:

composer test

Contributing

Contributions are welcome! Please ensure all tests pass and code follows ArtisanPack UI Code Standards.

Security

If you discover a security vulnerability, please send an email to security@artisanpack.com.

Credits

Jacob Martella
Intervention Image for image processing
PHP-FFMpeg for video processing

License

This package is proprietary software developed by ArtisanPack UI.

artisanpack-ui / media-library

Maintainers

Package info

Statistics

Security

README

Features

Core Features

New in v1.1

Requirements

Installation

Quick Start

What's New in v1.1

Livewire 4 Streaming Uploads

Visual Editor Integration

Media Statistics Dashboard

Table Export

AI features

Surfaces

Enabling the features

Documentation

Getting Started

Usage

Visual Editor Integration

Dashboard & Statistics

API & Integration

Reference

Testing

Contributing

Security

Credits

License