Replace file

What it does

Replace file swaps the on-disk file behind an existing library asset while keeping the same asset page ID. Every page reference field that already points at the asset continues to work. Rich-text embeds that carry data-mediahub-id stay linked to the same ID.

Use it when you need a new master (sharper photo, corrected export, updated PDF) without re-inserting the asset everywhere it appears. It is not available for YouTube/Vimeo embed assets; only real uploaded files.

What stays on the asset

Replace file changes the file on disk, not the asset page. Everything you already organised around that page stays put unless you edit it yourself:

• Library metadata: title, alt text, About, custom fields on the asset template, favourite flag, preview image on non-image assets
• Collections and labels: folder membership and library labels already assigned to the asset
• Usage and references: the same page ID, so MediaHub fields, usage records, and tracked rich-text embeds stay linked
• Image-specific file data: focus point and other per-file metadata on the ProcessWire file object are carried across to the new master (MediaHub snapshots and re-applies them during the swap)

You are updating the pixels or document, not creating a new library item.

Where to find it

Open any asset in the library, then use Actions → Replace file in the sidebar. The control appears for every non-embed asset that has a file on disk (raster images, SVG, video, audio, PDF, and other document types). See the Asset detail page overview for the rest of the Actions panel.

Workflow

1. Choose a file. Drag onto the drop zone or click to browse. The modal shows which file types are accepted for this asset (for example raster only for a JPEG master, SVG only for an SVG master, or the same extension for generic documents).
2. Review the confirmation. MediaHub shows the selected filename and size, how many pages reference the asset, and (for images) dimension notes when the new file differs from the current master. View current asset usage opens the Usage table in a new tab without losing your selection.
3. Filename choice. By default MediaHub keeps the asset's current filename on disk (only the extension may change if you upload a different format). That protects bookmarks and hard-coded URLs that point at the old name. Tick Use the new filename if you want the on-disk name to match the file you picked. When the name stays the same, browsers or a CDN may still show a cached copy until you hard-refresh; the summary reminds you after the job finishes.
4. Staged job. After you confirm, MediaHub swaps the file, then runs follow-up work in the same browser tab with plain-language progress:
   • Replace the master file (colour and size checks apply to raster images — see below)
   • Rebuild library and field crops when stored geometry still fits the preset (images only)
   • Re-warm ProcessWire image size variations where needed (images only)
   • Refresh tracked page output / cache where MediaHub knows a page uses the asset
5. Summary and reload. When every stage completes, a summary lists what succeeded and anything that needs a manual look, then the asset detail page reloads.

Keep the tab open until the summary appears. If the tab closes after the file has swapped but before later stages finish, reload the asset detail page. A banner can offer Run again for the remaining stages (job records expire after about an hour).

PDF, video, audio, and other documents

Replace file uses the same asset page, collections, labels, and reference rules for non-image files. The replacement must stay in the same category as the current file (for example PDF for PDF, video for video). You cannot turn a PDF asset into a JPEG or swap raster and SVG.

For these assets the staged job is typically shorter:

• Always: swap the master on disk and refresh page cache where MediaHub knows the asset is used.
• Often: regenerate an auto preview cover or update duration from the new file when the server supports it (same idea as after a fresh upload).
• Not run: crop regeneration or ProcessWire image variation re-warm. Those stages only appear when the asset is an image with crops or on-disk size variations to rebuild.

Images: size, colour, and crops

Replacements follow the same rules as library upload and module image size limits:

• Oversize masters are resized to your configured maximum before the swap, or refused when the site is set to reject oversize uploads. The confirmation shows both the file you selected and the size MediaHub will store.
• Undersize masters are refused when minimum dimensions are configured.
• Wide-gamut profiled sources are converted to sRGB when the server can do so safely, or refused with a clear message. See Uploading → Colour profiles.

When geometry still matches each crop preset, existing crop pages are rebuilt from the new master instead of leaving stale files. Crops that no longer fit may be reported in the summary for you to adjust in the crop editor. New crops store normalised geometry so replacements can replay crop windows reliably.

Rich text and templates

MediaHub field references (page reference fields) need no action: they point at page IDs. Templates that call $asset->image()->width() on output use the new master automatically.

TinyMCE embeds (toolbar insert with data-mediahub-id) are different: layout is frozen in stored HTML.

• Automatic: when the replacement changes the master extension or variation filename pattern, MediaHub rewrites src/href URLs in those textarea fields (master and variation URLs) so links still resolve.
• Not automatic: width, height, alignment classes, or caption markup saved in the editor. If the new image is a different aspect ratio, the old pixel box remains until an editor changes it — images can look stretched or letterboxed depending on your CSS.

Full detail: Rich text → When a library master is replaced.

Logging and audit

Every replacement writes a structured audit entry to the media-hub log (who started it, old and new files, crops, rich-text references, regenerated sizes, failures, and the final result). These audit lines are always recorded, even when optional MediaHub logging is disabled under Configuration → Logging. If ProcessWire cannot save the log file, the same message is written to the server's PHP error log.

What it does not do

• Does not replace embed-only assets (YouTube/Vimeo).
• Does not let you turn a raster master into SVG or vice versa; file category must match what the asset already holds.
• Does not automatically resize rich-text layout dimensions when aspect ratio changes.
• Does not remove usage on other sites or fix hard-coded URLs in template PHP that bypass MediaHub's tracking.

See also

• Asset detail page
• Image cropping
• Field automation (crop-preset pre-generation and WebP sidecars, 1.22.30)
• Changelog → 1.22.30