ArtisanPack UI
DocsMedia LibraryConfiguration

Configuration

Media Library v1.5.0

This guide covers all configuration options for the ArtisanPack UI Media Library package. The package configuration is merged into under the key. To...

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

Register additional sizes at runtime:

// 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:

  1. config('artisanpack.cms-framework.user_model')
  2. config('auth.providers.users.model')
  3. 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

v1.1 Features

Stay in the Loop

Monthly tips, tutorials and package updates — plus a free Quick Start cheat sheet.

Subscribe
Edit this page on GitHub