Media OS

Media OS gives your application one API for storing files on Laravel disks, generating image variants, connecting Spatie Media Library, scanning files and managing temporary uploads. Use it directly in your application services or through FLEX File Upload. Laravel filesystems Optional Spatie

Choose your integration

Storage API

Store uploads, local files, streams and bytes using a typed write policy.

Configuration

Choose disks, limits, visibility, worker settings and cleanup policies.

Image conversions

Generate thumbnails and WebP/AVIF variants, synchronously or in a worker.

Spatie integration

Use collections, native conversions, responsive images and model relationships.

Temporary uploads

Handle staging, record acceptance, recovery and abandoned files.

Extensions and events

Connect your antivirus scanner, processors and access policy.

Capture and retention

Configure transcription, signature evidence and retention services.

Browser integrations

Build a custom capture interface with the public browser helpers.

Understand the upload lifecycle

is separate from transfer completion. Queued conversion files can become available after the record has been saved.

Your first stored file

The following example stores a PDF on the Laravel local disk. $path is a readable local path supplied by your application. Import the classes shown in each example into the class where you use them.

use Bjanczak\FilamentFlexFields\Support\Media\FlexMedia;
use Bjanczak\FilamentFlexFields\Support\Media\Data\MediaPolicy;
use Bjanczak\FilamentFlexFields\Support\Media\Data\MediaWrite;
use Bjanczak\FilamentFlexFields\Support\Media\Sources\MediaSource;

$intent = new MediaWrite(
    disk: 'local',
    directory: 'contracts',
    policy: new MediaPolicy(
        maxBytes: 10 * 1024 * 1024,
        mimeTypes: ['application/pdf'],
    ),
);

$receipt = FlexMedia::store(MediaSource::path($path, 'contract.pdf'), $intent);

The result is a MediaReceipt. Save the attachment reference in your own model or use a FLEX upload field to manage form persistence for you.

$attachment->disk = $receipt->disk;
$attachment->path = $receipt->path;
$attachment->mime_type = $receipt->file->mimeType;
$attachment->size = $receipt->file->bytes;
$attachment->save();

A successful browser transfer and a saved record are different milestones. With a FLEX field, choosing a file transfers it to temporary storage; the form’s save flow creates and accepts the permanent attachment. Background thumbnail generation is a third, independent step.

Files and images in forms

use Bjanczak\FilamentFlexFields\Filament\Forms\Components\FlexFileUpload;

FlexFileUpload::make('contract')
    ->withRecommendedDefaults()
    ->acceptedFileTypes(['application/pdf'])
    ->disk('local')
    ->directory('contracts');

use Bjanczak\FilamentFlexFields\Filament\Forms\Components\FlexImageUpload;

FlexImageUpload::make('photos')
    ->withRecommendedDefaults()
    ->multiple()
    ->uploadLayout('grid')
    ->reorderable()
    ->maxFiles(10);

What is included

Inspected MIME types, byte limits, SHA-256 integrity checks and private/public visibility.
Local disks and configured cloud disks, including S3, through Laravel’s filesystem.
Named native image conversions, separate conversion disks, optimized previews and optional background jobs.
Optional Spatie collections, conversions, responsive images and custom properties.
Configurable antivirus integrations, processing, access policies and Laravel events.
Temporary staging, explicit recovery and scheduled cleanup.
Configurable capture transcription, signature evidence and retention services.

Media OS does not include an antivirus engine or a cloud-storage account. Configure those services in your application when you enable them. Disk storage does not require Spatie. Native raster conversions require PHP GD; the available output codecs depend on your GD installation.

Originals and converted files

Image conversions retain the original and create additional files. This applies to native synchronous conversions, native queued conversions and Spatie conversions. An optimized preview does not mean the original has been deleted.

If your storage policy permits only a reduced master image and a thumbnail, normalize the source before permanent storage, then create the thumbnail from that normalized master. There is no built-in conversion option that deletes the stored original while keeping its derivative records. Learn about originals and previews.

Configuration and next steps

The configuration namespace is filament-flex-fields.media_capture. Per-operation MediaWrite and MediaPolicy objects let you override storage and validation for a particular upload.

$intent = new MediaWrite(
    disk: 's3',
    directory: 'products/photos',
    policy: new MediaPolicy(
        maxBytes: 5 * 1024 * 1024,
        mimeTypes: ['image/jpeg', 'image/png', 'image/webp'],
        visibility: 'public',
    ),
);

Continue with configuration, storage examples or FLEX upload fields.

Storage and images

Lifecycle and integrations

Choose your integration

Storage API

Configuration

Image conversions

Spatie integration

Temporary uploads

Extensions and events

Capture and retention

Browser integrations

Understand the upload lifecycle

Your first stored file

Files and images in forms

What is included

Originals and converted files

Configuration and next steps

​Choose your integration

Storage API

Configuration

Image conversions

Spatie integration

Temporary uploads

Extensions and events

Capture and retention

Browser integrations

​Understand the upload lifecycle

​Your first stored file

​Files and images in forms

​What is included

​Originals and converted files

​Configuration and next steps

Choose your integration

Understand the upload lifecycle

Your first stored file

Files and images in forms

What is included

Originals and converted files

Configuration and next steps