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).

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.