> ## Documentation Index
> Fetch the complete documentation index at: https://flex-fields.bjanczak.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Examples target Filament 5. Verify optional dependencies before configuring integrations.
> Upload transfer completion, permanent storage and record acceptance are separate milestones. Native and Spatie image conversions retain the original.

# Updating existing media integrations

> Move existing application storage configuration to the typed Media OS API.

Existing capture helpers remain available as compatibility entry points. For new application storage code, prefer `FlexMedia::store()` with `MediaSource`, `MediaWrite` and typed failure handling. This guide concerns your application API usage; it does not require you to move existing files automatically.

## Replace capture-style persistence

```php theme={"theme":{"light":"github-light","dark":"github-dark"}}
use Bjanczak\FilamentFlexFields\Support\Media\FlexMedia;
use Bjanczak\FilamentFlexFields\Support\Media\Data\MediaWrite;
use Bjanczak\FilamentFlexFields\Support\Media\Sources\MediaSource;

$receipt = FlexMedia::store(
    MediaSource::path($filePath, 'document.pdf'),
    new MediaWrite(disk: 'local', directory: 'documents'),
);
```

A typed storage operation throws `MediaFailure` on rejection rather than returning an unqualified null result. [Failure handling](https://flex-fields.bjanczak.com/docs/media-os-api.md#handle-rejection).

## Replace scanner callbacks

Implement and register `MediaScanner` through `MediaExtensions::scanner()`. The old boolean callback must return exactly true to certify a clean file; the new contract returns normally or throws. [Scanner example](https://flex-fields.bjanczak.com/docs/media-os-extensions.md#antivirus-scanner).

## Existing paths and historical thumbnails

Existing path-only attachments remain readable. New named conversion bundles retain owned receipts for their original and derivatives. Historical thumbnails are not inferred from a guessed filename: inventory and migrate your old derivative references explicitly before expecting bundle deletion to remove them.

## Existing form fields

Disk state remains paths; Spatie state remains Media UUIDs. Add per-operation policies or callbacks without replacing the native field's storage callback:

```php theme={"theme":{"light":"github-light","dark":"github-dark"}}
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\FlexFileUpload;

FlexFileUpload::make('documents')->multiple()
    ->mediaMetadata(['purpose' => 'customer-documents']);
```

If your application replaces Filament's save lifecycle, call `completeMediaUploadsAfterSave($record)` on the mounted field after persisting its reference. [Save integration](https://flex-fields.bjanczak.com/docs/file-upload-events-and-recovery.md#create-and-edit-forms).

## Queue changes

Synchronous disk conversions remain the default. Enable background conversion explicitly only after configuring shared storage and a durable worker. Spatie continues using its native model-defined conversion jobs. [Native queue setup](https://flex-fields.bjanczak.com/docs/media-os-images.md#background-conversions) · [Spatie queues](https://flex-fields.bjanczak.com/docs/media-os-spatie.md#queued-conversions).

## Originals

Named conversions and optimization preserve originals. An optimized preview/path is not evidence that the source has been deleted. Choose your source-normalization policy before permanent storage if you want a smaller master. [Original retention](https://flex-fields.bjanczak.com/docs/media-os-images.md#original-retention).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.