Media Library - v1.1.0

Configuration

This guide covers all configuration options for the ArtisanPack UI Media Library package.

Configuration File

The package configuration is merged into config/artisanpack.php under the media key.

To publish the configuration:

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

Configuration Options

Storage Settings

`disk`

The storage disk to use for media uploads.

'disk' => env('MEDIA_DISK', 'public'),

Environment variable:

MEDIA_DISK=public

Common values:

public - Local public storage (default)
s3 - Amazon S3
gcs - Google Cloud Storage
azure - Azure Blob Storage

`max_file_size`

Maximum file size in kilobytes.

'max_file_size' => env('MEDIA_MAX_FILE_SIZE', 10240),

Environment variable:

MEDIA_MAX_FILE_SIZE=10240  # 10 MB

Note: Also configure your web server and php.ini accordingly.

`upload_path_format`

Format for organizing uploaded files in directories.

'upload_path_format' => env('MEDIA_UPLOAD_PATH_FORMAT', '{year}/{month}'),

Environment variable:

MEDIA_UPLOAD_PATH_FORMAT={year}/{month}

Available placeholders:

{year} - Four-digit year (e.g., 2025)
{month} - Two-digit month (e.g., 01)
{day} - Two-digit day (e.g., 15)
{user_id} - User ID of uploader

Examples:

{year}/{month} → 2025/01/
{year}/{month}/{day} → 2025/01/15/
users/{user_id} → users/123/

Image Processing

`enable_modern_formats`

Enable automatic conversion to modern image formats (WebP/AVIF).

'enable_modern_formats' => env('MEDIA_ENABLE_MODERN_FORMATS', true),

Environment variable:

MEDIA_ENABLE_MODERN_FORMATS=true

When enabled, the package creates modern format versions alongside originals.

`modern_format`

Which modern format to use: webp or avif.

'modern_format' => env('MEDIA_MODERN_FORMAT', 'webp'),

Environment variable:

MEDIA_MODERN_FORMAT=webp

Options:

webp - WebP format (widely supported)
avif - AVIF format (better compression, requires Imagick)

`image_quality`

Image quality for processed images (1-100).

'image_quality' => env('MEDIA_IMAGE_QUALITY', 85),

Environment variable:

MEDIA_IMAGE_QUALITY=85

Guidelines:

100 - Highest quality, largest file size
85 - Recommended balance (default)
60-70 - Lower quality, smaller files

`enable_thumbnails`

Enable automatic thumbnail generation.

'enable_thumbnails' => env('MEDIA_ENABLE_THUMBNAILS', true),

Environment variable:

MEDIA_ENABLE_THUMBNAILS=true

Image Sizes

Define default image sizes to generate.

'image_sizes' => [
    'thumbnail' => [
        'width' => 150,
        'height' => 150,
        'crop' => true,
    ],
    'medium' => [
        'width' => 300,
        'height' => 300,
        'crop' => false,
    ],
    'large' => [
        'width' => 1024,
        'height' => 1024,
        'crop' => false,
    ],
],

Options:

width - Maximum width in pixels
height - Maximum height in pixels
crop - Whether to crop or resize proportionally

Registering Custom Image Sizes

// In a service provider or plugin
apRegisterImageSize('hero-banner', 1920, 600, true);
apRegisterImageSize('product-grid', 400, 400, true);

Access in configuration:

'custom_image_sizes' => [
    // Runtime-registered sizes appear here
],

Allowed MIME Types

Define which file types are allowed for upload.

'allowed_mime_types' => [
    // Images
    'image/jpeg',
    'image/jpg',
    'image/png',
    'image/gif',
    'image/webp',
    'image/avif',
    'image/svg+xml',

    // Videos
    'video/mp4',
    'video/mpeg',
    'video/quicktime',
    'video/webm',

    // Audio
    'audio/mpeg',
    'audio/wav',
    'audio/ogg',

    // Documents
    'application/pdf',
    'application/msword',
    'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
    'application/vnd.ms-excel',
    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
],

To add custom types:

'allowed_mime_types' => array_merge(config('artisanpack.media.allowed_mime_types'), [
    'application/zip',
    'text/plain',
]),

User Model

The User model to use for relationships.

'user_model' => null, // Auto-detected

The package automatically detects the User model from:

config('artisanpack.cms-framework.user_model')
config('auth.providers.users.model')
Falls back to App\Models\User

To override:

'user_model' => App\Models\CustomUser::class,

Environment Variables Reference

Complete list of environment variables:

# Storage
MEDIA_DISK=public
MEDIA_MAX_FILE_SIZE=10240
MEDIA_UPLOAD_PATH_FORMAT={year}/{month}

# Image Processing
MEDIA_ENABLE_MODERN_FORMATS=true
MEDIA_MODERN_FORMAT=webp
MEDIA_IMAGE_QUALITY=85
MEDIA_ENABLE_THUMBNAILS=true

# Feature Flags (v1.1)
MEDIA_STREAMING_UPLOAD=true
MEDIA_STREAMING_FALLBACK_INTERVAL=500

# UI Settings (v1.1)
MEDIA_GLASS_EFFECTS=true
MEDIA_STATS_ENABLED=true
MEDIA_TABLE_EXPORT=true

Cloud Storage Configuration

Amazon S3

In config/filesystems.php:

's3' => [
    'driver' => 's3',
    'key' => env('AWS_ACCESS_KEY_ID'),
    'secret' => env('AWS_SECRET_ACCESS_KEY'),
    'region' => env('AWS_DEFAULT_REGION'),
    'bucket' => env('AWS_BUCKET'),
    'url' => env('AWS_URL'),
    'endpoint' => env('AWS_ENDPOINT'),
],

In .env:

MEDIA_DISK=s3
AWS_ACCESS_KEY_ID=your-key
AWS_SECRET_ACCESS_KEY=your-secret
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=your-bucket

Google Cloud Storage

In config/filesystems.php:

'gcs' => [
    'driver' => 'gcs',
    'key_file_path' => env('GOOGLE_CLOUD_KEY_FILE'),
    'project_id' => env('GOOGLE_CLOUD_PROJECT_ID'),
    'bucket' => env('GOOGLE_CLOUD_BUCKET'),
],

Azure Blob Storage

In config/filesystems.php:

'azure' => [
    'driver' => 'azure',
    'name' => env('AZURE_STORAGE_NAME'),
    'key' => env('AZURE_STORAGE_KEY'),
    'container' => env('AZURE_STORAGE_CONTAINER'),
],

Feature Flags (v1.1)

Control which features are enabled in your application.

Streaming Uploads

`features.streaming_upload`

Enable Livewire 4's wire:stream for real-time upload progress.

'features' => [
    'streaming_upload' => env('MEDIA_STREAMING_UPLOAD', true),
],

Environment variable:

MEDIA_STREAMING_UPLOAD=true

When enabled on Livewire 4+, uploads show real-time progress via wire:stream. On Livewire 3, automatically falls back to polling.

`features.streaming_fallback_interval`

Polling interval (milliseconds) for Livewire 3 fallback.

'features' => [
    'streaming_fallback_interval' => env('MEDIA_STREAMING_FALLBACK_INTERVAL', 500),
],

Environment variable:

MEDIA_STREAMING_FALLBACK_INTERVAL=500

Lower values provide smoother progress updates but increase server load.

UI Settings (v1.1)

Glass Effects

Enable modern glassmorphism UI effects.

`ui.glass_effects.enabled`

Enable or disable glass effects globally.

'ui' => [
    'glass_effects' => [
        'enabled' => env('MEDIA_GLASS_EFFECTS', true),
    ],
],

Environment variable:

MEDIA_GLASS_EFFECTS=true

`ui.glass_effects.card_overlay`

Configuration for card overlay glass effects.

'ui' => [
    'glass_effects' => [
        'card_overlay' => [
            'blur' => 'md',
            'opacity' => 80,
        ],
    ],
],

Options:

blur - Blur intensity: sm, md, lg, xl, 2xl, 3xl
opacity - Background opacity: 0-100

`ui.glass_effects.modal_backdrop`

Configuration for modal backdrop glass effects.

'ui' => [
    'glass_effects' => [
        'modal_backdrop' => [
            'blur' => 'sm',
            'opacity' => 50,
        ],
    ],
],

Statistics Dashboard

Configure the media statistics component.

`ui.stats_dashboard.enabled`

Enable the statistics dashboard.

'ui' => [
    'stats_dashboard' => [
        'enabled' => env('MEDIA_STATS_ENABLED', true),
    ],
],

Environment variable:

MEDIA_STATS_ENABLED=true

`ui.stats_dashboard.sparkline_days`

Number of days to show in sparkline charts.

'ui' => [
    'stats_dashboard' => [
        'sparkline_days' => 30,
    ],
],

`ui.stats_dashboard.refresh_interval`

Auto-refresh interval in seconds (0 to disable).

'ui' => [
    'stats_dashboard' => [
        'refresh_interval' => 0,
    ],
],

Table Export

Configure export functionality for the media library table.

`ui.table_export.enabled`

Enable table export functionality.

'ui' => [
    'table_export' => [
        'enabled' => env('MEDIA_TABLE_EXPORT', true),
    ],
],

Environment variable:

MEDIA_TABLE_EXPORT=true

`ui.table_export.formats`

Available export formats.

'ui' => [
    'table_export' => [
        'formats' => ['csv', 'xlsx', 'pdf'],
    ],
],

Available formats:

csv - Comma-separated values
xlsx - Microsoft Excel format (requires PhpSpreadsheet)
pdf - PDF document (requires DOMPDF or similar)

`ui.table_export.max_rows`

Maximum rows to export (0 for unlimited).

'ui' => [
    'table_export' => [
        'max_rows' => 10000,
    ],
],

Visual Editor Integration (v1.1)

Configure MediaPicker for visual editor integration.

Recently Used Media

`visual_editor.track_recently_used`

Enable tracking of recently selected media.

'visual_editor' => [
    'track_recently_used' => true,
],

`visual_editor.recently_used_limit`

Maximum number of recently used items to track.

'visual_editor' => [
    'recently_used_limit' => 20,
],

Quick Upload Select

`visual_editor.quick_upload_select`

Automatically select newly uploaded media.

'visual_editor' => [
    'quick_upload_select' => true,
],

When enabled, media uploaded via the picker is automatically selected after upload completes.

Picker Settings

`visual_editor.picker.default_view`

Default view mode for the picker.

'visual_editor' => [
    'picker' => [
        'default_view' => 'grid',
    ],
],

Options: grid, list

`visual_editor.picker.items_per_page`

Number of items per page in the picker.

'visual_editor' => [
    'picker' => [
        'items_per_page' => 24,
    ],
],

`visual_editor.picker.show_folders`

Show folder sidebar in the picker.

'visual_editor' => [
    'picker' => [
        'show_folders' => true,
    ],
],

`visual_editor.picker.allow_upload`

Allow uploads from within the picker.

'visual_editor' => [
    'picker' => [
        'allow_upload' => true,
    ],
],

Block Requirements (v1.1)

Define media requirements for visual editor block types.

'block_requirements' => [
    'default' => [
        'allowed_types' => ['image', 'video', 'audio', 'document'],
        'max_file_size' => null, // Use global default
        'max_selections' => null, // No limit
    ],
    'image' => [
        'allowed_types' => ['image'],
        'max_file_size' => 5120, // 5 MB
        'max_selections' => 1,
    ],
    'gallery' => [
        'allowed_types' => ['image'],
        'max_file_size' => 5120,
        'max_selections' => 20,
    ],
    'video' => [
        'allowed_types' => ['video'],
        'max_file_size' => 102400, // 100 MB
        'max_selections' => 1,
    ],
    'audio' => [
        'allowed_types' => ['audio'],
        'max_file_size' => 20480, // 20 MB
        'max_selections' => 1,
    ],
    'document' => [
        'allowed_types' => ['document'],
        'max_file_size' => 10240, // 10 MB
        'max_selections' => 5,
    ],
    'hero' => [
        'allowed_types' => ['image'],
        'max_file_size' => 10240,
        'max_selections' => 1,
        'min_width' => 1920,
        'min_height' => 600,
    ],
    'background' => [
        'allowed_types' => ['image'],
        'max_file_size' => 5120,
        'max_selections' => 1,
    ],
],

Options per block type:

allowed_types - Array of allowed media types: image, video, audio, document
max_file_size - Maximum file size in KB for this block type
max_selections - Maximum number of media items that can be selected
min_width - Minimum image width (images only)
min_height - Minimum image height (images only)

Custom Block Types

Add custom block types to match your visual editor:

'block_requirements' => [
    // ... existing types ...
    'product-image' => [
        'allowed_types' => ['image'],
        'max_file_size' => 2048,
        'max_selections' => 1,
        'min_width' => 800,
        'min_height' => 800,
    ],
    'testimonial-avatar' => [
        'allowed_types' => ['image'],
        'max_file_size' => 1024,
        'max_selections' => 1,
    ],
],

Runtime Configuration

Override Configuration Values

You can override configuration at runtime:

config([
    'artisanpack.media.max_file_size' => 20480, // 20 MB
    'artisanpack.media.image_quality' => 90,
]);

CMS Module Integration

When using the Media module with Digital Shopfront CMS, settings can be configured through the admin interface at /admin/settings/media.

These settings override the default configuration at runtime.

Performance Optimization

Queue Configuration

For better performance, process images via queues:

In config/queue.php:

'connections' => [
    'media' => [
        'driver' => 'redis',
        'connection' => 'default',
        'queue' => 'media',
        'retry_after' => 600,
    ],
],

Run queue worker:

php artisan queue:work --queue=media

Caching

The package uses Laravel's cache for media metadata:

config([
    'cache.stores.media' => [
        'driver' => 'redis',
        'connection' => 'media',
    ],
]);

Next Steps

Learn about Helper Functions
Explore Model Usage
Set up Permissions
Review Customization options

v1.1 Features

Configure Streaming Uploads
Set up Table Export
Integrate with Visual Editors
Customize Media Statistics