Replace file
Swap the master file behind a library asset while keeping the same page ID, references, and usage. Side-by-side confirmation, optional mhv cache-busting, and Fit to new shape for rich text. Public beta from 1.22.30; 1.22.31 docs.
Public beta. Replace file shipped in MediaHub 1.22.30 (Beta); confirmation, cache-busting, and rich-text options below reflect 1.22.31. Test on staging first; 1.22.2 remains the recommended production release until this feature graduates.
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
- 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).
- Review the confirmation. MediaHub shows the current and new file side by side at the same scale, with format, dimensions, file size, and modified date under each preview. Usage counts and file details are refreshed when you pick the file, so they stay accurate if someone embedded the asset while you had the page open. Three groups explain what happens next:
- Changes — shape or size differences, how many pages use the asset (with a link to Usage), resize or limit warnings when they apply.
- Rich text — when the aspect ratio changes and the image is embedded in rich text, Fit to new shape is on by default (see below).
- Filename — two switches: Keep … (recommended so direct links keep working) or Rename to … (adopt the upload name).
- 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 page cache where needed — tracked usage and/or ProCache HTML search when cache-busting is enabled (see below)
- 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
Rich text and aspect ratio. When the new image has a different shape and the asset is embedded in tracked rich-text fields, the confirmation offers Fit to new shape (on by default). It keeps each image's saved width and recalculates height (and matching inline CSS) so the new file is not stretched. Explicit crop variations in the HTML (for example .500x500.jpg) are left alone. Turn it off to leave saved dimensions unchanged. Fixed-dimension crops saved in the editor are not bulk-edited across the site.
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/hrefURLs in those textarea fields (master and variation URLs) so links still resolve. - Optional (1.22.31): with Fit to new shape on the confirmation,
heightand inline height values are updated in tracked rich-text fields when aspect ratio changes.width, alignment, captions, and fixed crop filenames are still your responsibility when you turn the option off or when the embed does not use the master file.
Full detail: Rich text → When a library master is replaced.
Same filename and visitor cache (1.22.31)
Keeping the on-disk filename protects field references and hard-coded URLs, but browsers, hosting stacks, and CDNs can keep serving old bytes. Optional Cache-bust replaced files under Configuration → Replacing files adds mhv= plus the replacement timestamp to that asset's URLs in front-end HTML output only. Page content in the database is never changed. When enabled, the replacement summary notes that visitors get the new file automatically. Without it, you may still need a hard refresh or a CDN purge on aggressive caches.
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 unless you leave Fit to new shape on when aspect ratio changes (and then only
height/ inline height — not width, crops, or captions). - 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)
- Configuration → Replacing files
- Changelog → 1.22.31
Last updated