Replace & duplicate

The Media Library ships with two actions that let you work with existing files without disrupting the rest of your application: replace swaps the binary on disk while keeping the same record, and duplicate creates an independent sibling copy with a new ID. Both actions work on the Media Library Item driver and the Spatie Media Library driver.

Replacing a file

The replace action lets you upload a new file in place of an existing one. The key property of a replace is that the media record's primary key is preserved – the underlying database row stays the same, so any references to that file in your application (foreign keys, stored IDs, URLs that embed the key) continue to work without any changes on your end.

Internally the driver writes the new binary to the same disk path, updates the stored file name, MIME type, and size on the media record, and then regenerates any image conversions and responsive images. The old binary is removed.

The replace action appears in the file info panel – the sidebar that opens when you select a single file. It is part of the default fileInfoActions set and is not shown for folders, only for files.

Accepted file types

The file upload in the replace modal is constrained to the same accepted file types that the driver is configured with. The new file does not have to be the same type as the original, but it must pass the driver's accepted-types check.

Customising the replace action

You can swap out or reconfigure the full set of file info actions (including replace) by calling ->fileInfoActions() on your driver:

use RalphJSmit\Filament\Explore;

$driver->fileInfoActions([
    Explore\Filament\Actions\PreviewAction::make(),
    Explore\Filament\Actions\MoveAction::make(),
    Explore\Filament\Actions\RenameAction::make(),
    Explore\Filament\Actions\ReplaceAction::make(),
    Explore\Filament\Actions\EditImageAction::make(),
    Explore\Filament\Actions\DeleteAction::make(),
]);

Omit ReplaceAction::make() from the array to remove the action entirely.

Duplicating a file

The duplicate action creates a sibling copy of a file in the same folder, assigning it a brand-new primary key. The copy inherits the original's binary, alt text, and caption, but is otherwise independent – changes to the duplicate do not affect the original.

When you trigger the action on a single file a modal asks you to confirm or change the name for the copy. The default name is {original filename} (copy). When you run the duplicate bulk action on multiple files at once, the names are resolved automatically: the first copy gets (copy), subsequent clashes are resolved with a numeric counter ((1), (2), …).

Duplicating a folder recursively copies its entire contents.

The single-file DuplicateAction appears in the file actions dropdown on each item in the grid (inside the grouped action menu, alongside Rename and Download). The DuplicateBulkAction is available as a bulk action in the toolbar when one or more items are selected.

Customising the duplicate action

Use ->fileActions() to control which actions appear per file, and ->bulkActions() to control the bulk toolbar:

use RalphJSmit\Filament\Explore;
use Filament\Actions\ActionGroup;
use Filament\Support\Icons\Heroicon;

$driver->fileActions([
    Explore\Filament\Actions\MoveAction::make(),
    Explore\Filament\Actions\DeleteAction::make(),
    ActionGroup::make([
        Explore\Filament\Actions\RenameAction::make(),
        Explore\Filament\Actions\DuplicateAction::make(),
        Explore\Filament\Actions\DownloadAction::make(),
    ]),
]);

$driver->bulkActions([
    Explore\Filament\Actions\DeleteBulkAction::make(),
    Explore\Filament\Actions\DuplicateBulkAction::make(),
]);

The provided action arrays replace the defaults entirely, so make sure to include any actions you still want to keep.