Prompt file imported from anisAronno/laravel-vue-dashbaord (.github/prompts/mideaGallery.prompt.md). Copyright stays with the author.

Define the task to achieve, including specific requirements, constraints, and success criteria.

Laravel Media Gallery Module

Project Overview

Create a comprehensive, reusable Laravel package for file/media management with gallery functionality, similar to WordPress media library but optimized for Laravel applications.

Technical Stack

• Laravel: 12.x
• PHP: 8.2+
• Frontend: Inertia.js 2 + Vue.js 3 + TypeScript
• Styling: Tailwind CSS
• Environment: Docker
• Testing: PHPUnit (TDD approach)

Core Requirements

1. Package Structure

• Must be a standalone Laravel package/module
• Installable via Composer
• No code inside main project - only package setup code
• Self-contained with proper service provider registration

2. Database Design & Architecture

Models & Relationships

// Media Model
- id, original_name, hash_name, mime_type, extension, size, path
- meta_data (JSON: title, alt_text, description, seo_title, seo_description)
- optimized_versions (JSON: array of generated sizes)
- created_at, updated_at

// MediaDirectory Model
- id, model_type, model_id, extension_type, date_path, created_at

// Pivot Table: model_media
- model_type, model_id, media_id
- pivot_data (JSON: for additional tracking data)
- attached_at, detached_at

Directory Structure Logic

storage/app/media/
├── {model_name}/
│   ├── images/
│   │   └── 2025-03-07/
│   │       ├── originals/
│   │       ├── thumbnails/
│   │       ├── small/
│   │       ├── medium/
│   │       └── large/
│   ├── pdfs/
│   │   └── 2025-03-07/
│   └── videos/
│       └── 2025-03-07/

3. HasMedia Trait Implementation

Core Methods Required

trait HasMedia {
    // Relationships
    public function media()
    public function images()
    public function pdfs()

    // Attachment Methods
    public function attachMedia($mediaIds, $pivotData = [])
    public function detachMedia($mediaIds = null)
    public function syncMedia($mediaIds, $pivotData = [])

    // Retrieval Methods
    public function getMedia($type = null, $size = null)
    public function getFirstMedia($type = null, $size = null)
    public function hasMedia($type = null)

    // URL Generation
    public function getMediaUrl($mediaId, $size = 'original')
    public function getFirstMediaUrl($type = null, $size = 'original')
}

4. Image Processing & Optimization

Configuration-Based Sizing

// Config: media-gallery.php
'image_sizes' => [
    'thumbnail' => ['width' => 150, 'height' => 150, 'crop' => true],
    'small' => ['width' => 300, 'height' => 300, 'crop' => false],
    'medium' => ['width' => 600, 'height' => 400, 'crop' => false],
    'large' => ['width' => 1200, 'height' => 800, 'crop' => false],
    'custom' => ['width' => null, 'height' => null, 'crop' => false], // Dynamic sizing
],

'optimization' => [
    'enabled' => true,
    'quality' => 85,
    'progressive' => true,
    'strip_meta' => true,
],

'validation' => [
    'max_file_size' => '10MB',
    'allowed_images' => ['jpg', 'jpeg', 'png', 'webp', 'svg'],
    'allowed_documents' => ['pdf', 'doc', 'docx', 'txt'],
    'allowed_videos' => ['mp4', 'mov', 'avi'],
],

5. Frontend Components (Vue 3 + TypeScript)

Core Components Needed

1. MediaGalleryModal.vue

   • Props: show, multiple, acceptedTypes, customSizes
   • Features: Directory tabs, pagination, search, filter by type
   • Events: @selected, @closed

2. MediaUploader.vue

   • Drag & drop interface
   • Multiple file selection
   • Progress indicators
   • Image cropping functionality
   • Validation feedback

3. MediaInput.vue

   • Form integration component
   • Shows selected media previews
   • Remove/detach functionality
   • Opens gallery modal

4. MediaPreview.vue

   • Display component for different file types
   • Hover actions (delete, edit metadata)
   • Size variant selector

Frontend Features

• Gallery Modal Tabs: Organized by directory structure
• Pagination: Load more with infinite scroll
• Search & Filter: By filename, type, date
• Bulk Actions: Select multiple, bulk delete/detach
• Image Cropping: Before upload with custom ratios
• Drag & Drop: Modern file upload experience

6. API Design

REST Endpoints

// Media Management
GET /api/media-gallery/media - List media with filters
POST /api/media-gallery/upload - Upload new files
PUT /api/media-gallery/media/{id} - Update media metadata
DELETE /api/media-gallery/media/{id} - Delete media file

// Model Media Relationships
GET /api/media-gallery/{model}/{id}/media - Get model's media
POST /api/media-gallery/{model}/{id}/attach - Attach media to model
DELETE /api/media-gallery/{model}/{id}/detach - Detach media from model
PUT /api/media-gallery/{model}/{id}/sync - Sync media with model

// Gallery Interface
GET /api/media-gallery/directories - Get directory structure
GET /api/media-gallery/media/search - Search media files
POST /api/media-gallery/media/bulk-action - Bulk operations

7. Testing Requirements (TDD Approach)

Test Coverage Areas

• Unit Tests: All trait methods, media model methods
• Feature Tests: API endpoints, file upload/download
• Integration Tests: Model relationships, directory structure
• Browser Tests: Frontend component interactions

Example Test Cases

// Trait functionality
test_model_can_attach_media()
test_model_can_detach_media()
test_model_can_sync_media()
test_model_can_retrieve_media_by_type()

// File operations
test_file_upload_creates_optimized_versions()
test_file_upload_organizes_by_directory_structure()
test_file_deletion_removes_all_versions()

// API endpoints
test_media_gallery_api_returns_paginated_results()
test_media_upload_validates_file_types_and_sizes()
test_bulk_operations_work_correctly()

8. Performance & Optimization

Requirements

• Lazy Loading: Images load as needed
• Caching: Directory listings, media queries
• CDN Ready: Configurable asset URLs
• Database Optimization: Proper indexing, efficient queries
• Memory Management: Large file handling without memory issues

9. Configuration & Customization

Package Configuration

• File type restrictions per model
• Custom image sizes and optimization settings
• Storage driver configuration (local, S3, etc.)
• Custom validation rules
• UI customization options

10. Installation & Setup

Package Requirements

{
    "name": "your-vendor/laravel-media-gallery",
    "require": {
        "php": "^8.2",
        "laravel/framework": "^11.0|^12.0",
        "intervention/image": "^3.0",
        "spatie/laravel-medialibrary": "^11.0"
    }
}

Setup Commands

composer require your-vendor/laravel-media-gallery
php artisan media-gallery:install
php artisan media-gallery:migrate
php artisan media-gallery:publish-config

User Experience Goals

WordPress-like Experience

• Intuitive media library interface
• Drag & drop functionality
• Bulk selection and operations
• Real-time search and filtering
• Responsive design for all screen sizes

Developer Experience

• Simple trait integration: use HasMedia
• Fluent API for media operations
• Comprehensive documentation
• Easy customization and extension
• Minimal setup required

Success Criteria

1. Performance: Handle 1000+ media files without performance degradation
2. Usability: Non-technical users can manage media easily
3. Flexibility: Supports various file types and custom sizing requirements
4. Maintainability: Clean, tested, well-documented codebase
5. Extensibility: Easy to add new features or customize existing ones

Deliverables

1. Complete Laravel package with proper structure
2. Comprehensive test suite (90%+ coverage)
3. Frontend components (Vue 3 + TypeScript)
4. API documentation
5. Installation and usage documentation
6. Configuration examples
7. Demo application showing integration

Note: This project emphasizes clean architecture, SOLID principles, and test-driven development while avoiding over-engineering. The focus is on creating a production-ready, maintainable solution that can be easily integrated into existing Laravel applications.