Migration Guide: Moving Sites to MediaHub

Before you start

The recommended approach is to run both systems side by side: keep your existing image fields in place while gradually importing assets into MediaHub and wiring up the new fields. Once everything is confirmed working, remove the old fields and clean up legacy files.

Step 1: Set up the library

Install MediaHub and configure it via Modules → Configure → MediaHub. Set your allowed file extensions, upload size limits, and crop presets. See the Configuration page for details.

At this point the library is empty and your existing site continues to work exactly as before.

Step 2: Add MediaHub fields alongside existing image fields

Create a MediaHub field (a page reference field using the MediaHub Picker inputfield) and add it to every template that currently has a traditional image field. Do not remove the existing image fields yet.

Your templates now have both fields available: the original FieldtypeImage field and the new MediaHub page reference field. This is the dual-running state that lets you migrate incrementally.

Step 3: Import existing images

You have two import routes, and they work well together:

• Global scan (Importing Assets): crawls the entire site and lets you bulk-import images into the library. Best for an initial mass import.
• Per-field import (Import Page Images): a button on each page that scans the other image fields on that specific page, matches against the library with deduplication, and imports or links as appropriate. Best for page-by-page migration as editors work through the site.

Both routes carry over descriptions as alt text, convert PW image tags to Hub tags, and record the source page and field in the asset's About field as an audit trail.

Step 4: Update your templates

With both fields on each template, you can update your template code to prefer MediaHub when an asset is available, falling back to the traditional image field when it is not. This lets you launch the new fields before every page has been migrated.

Basic fallback pattern

<?php
$hubImage = $page->mediahub_hero->first();
$legacyImage = $page->hero_image;
if ($hubImage) {
$img = $hubImage->image()->size(1200, 630);
echo "<img src='{$img->url}' alt='{$hubImage->altText()}'>";
} elseif ($legacyImage) {
$img = $legacyImage->size(1200, 630);
echo "<img src='{$img->url}' alt='{$legacyImage->description}'>";
}
?>

Visual indicator for development

During migration, it is useful to see at a glance which images on a rendered page are coming from MediaHub and which are still served from the legacy field. A simple data attribute makes this easy to spot in browser DevTools or via a quick CSS highlight:

<?php
if ($hubImage) {
$img = $hubImage->image()->size(1200, 630);
echo "<img src='{$img->url}' alt='{$hubImage->altText()}' data-source='mediahub'>";
} elseif ($legacyImage) {
$img = $legacyImage->size(1200, 630);
echo "<img src='{$img->url}' alt='{$legacyImage->description}' data-source='legacy'>";
}
?>

You can then add a temporary CSS rule during development to visually flag legacy images:

img[data-source="legacy"] { outline: 3px dashed red; }
img[data-source="mediahub"] { outline: 3px solid green; }

This makes it immediately obvious which pages still need attention.

Config-driven switch

For larger sites, you may want a site-wide toggle that controls whether templates prefer MediaHub or fall back to legacy images. Add a setting to your site/config.php:

$config->mediahubPriority = true; // Set to false to revert to legacy

Then reference it in your templates:

<?php
$useHub = $config->mediahubPriority;
$hubImage = $useHub ? $page->mediahub_hero->first() : null;
$legacyImage = $page->hero_image;
$source = $hubImage ?: $legacyImage;
if ($source) {
if ($hubImage) {
$img = $hubImage->image()->size(1200, 630);
$alt = $hubImage->altText();
} else {
$img = $legacyImage->size(1200, 630);
$alt = $legacyImage->description;
}
echo "<img src='{$img->url}' alt='{$alt}'>";
}
?>

When you are confident all images have been migrated, flip $config->mediahubPriority to true (or remove the fallback logic entirely) and every page instantly switches to MediaHub images.

Step 5: Clean up

Once migration is complete and verified:

1. Remove the legacy image fields from your templates in Setup → Templates
2. Delete the legacy image field definitions from Setup → Fields (if no other templates use them)
3. Remove the fallback logic and data-source attributes from your template code
4. Clean up orphaned image files from site/assets/files/ for pages that no longer have image fields

Upgrading from 1.9.x to 1.10

No database changes or manual steps are required when upgrading to 1.10. Run Modules → Refresh in the ProcessWire admin, then upgrade the module.

One behaviour change worth noting: logging is now off by default. In previous versions, MediaHub wrote to site/assets/logs/media-hub.txt automatically. After upgrading, that file will stop growing. If you rely on the log for debugging or monitoring, go to Modules → Configure → MediaHub → Logging and enable it explicitly.

Tips

• Migrate high-traffic or frequently edited templates first; low-traffic archival pages can wait.
• The per-field import button is the safest page-by-page approach because its deduplication logic avoids creating duplicate assets when an image is already in the library.
• Editors can use the per-field import as they naturally edit pages, spreading the migration workload over time rather than requiring a dedicated sprint.
• If you have hundreds of pages, consider scripting the fallback pattern into a shared function or include file so changes only need to be made in one place.