Menu

Let's Talk
Docs MediaHub Version 1.x Getting Started

Getting Started

What MediaHub is, why you might want it, and what to expect before you install.

The problem it solves

ProcessWire's native image and file fields are attached to individual pages. That works well for per-page content, but it gets awkward fast when the same asset needs to appear in multiple places. A logo, a press release PDF, a product shot used across a dozen pages; you end up either uploading the same file several times or writing fragile workarounds to reference files from elsewhere in the tree.

MediaHub adds a site-wide media library. You upload once, and that asset is available to every template on the site. Update the alt text or swap the file, and it updates everywhere it's used.

How it works

MediaHub creates a dedicated branch in your ProcessWire page tree (hidden from front-end navigation) where all uploaded assets live. Each asset is its own page, carrying metadata like alt text, tags, collections, and a usage log of which pages reference it.

In your templates, a MediaHub field returns a standard ProcessWire page reference. For images, call ->image() to get a Pageimage and every native PW image method (width(), height(), size(), srcset()) works as you'd expect. For non-image assets (PDFs, videos, audio), call ->file() for the Pagefile or ->fileUrl() for the download URL. Type-checking helpers like ->isImage(), ->isDocument(), ->isVideo(), and ->isAudio() let you branch your output by asset type.

Two things, not one

After installation you'll notice two separate things in the ProcessWire admin, and it's worth being clear about what each one is:

/pkd-mediahub/                     ← data storage (page tree)
    /tags/
    /collections/
    /assets/
    /crops/

/processwire/setup/media-hub/      ← the admin UI you interact with

The page tree branch at /pkd-mediahub/ is the data storage layer. Assets, tags, collections, and crop pages all live here as standard ProcessWire pages in the database; that's how PW stores structured data. It is not a public-facing page. It has no front-end template, is marked as a system page, and won't appear anywhere on your site. You'll only see it in the admin page tree because you're logged in as a superuser.

The admin UI at Setup → Media Hub is the interface you actually use day-to-day. It reads from those storage pages and presents the library, upload screen, asset detail pages, and everything else.

If you see /pkd-mediahub/ in the page tree and wonder what it is: that's the storage branch. Leave it alone; the admin UI is where you manage your media.

What you get

  • A central library browsable by search, type, tag, or collection
  • Drag-and-drop upload with configurable file type and size limits
  • A built-in crop editor with nine aspect ratio presets and support for custom ones
  • Inline crop badges in the page editor: crops for configured presets are auto-generated at render time, and editors can click any badge to adjust the crop position without leaving the page
  • Per-asset usage tracking: the asset detail page lists every ProcessWire page that references it
  • Per-reference metadata: override alt text and assign context-specific tags per page, without touching the global asset
  • Collections (folders, albums, galleries; the label is configurable) for hierarchical organisation
  • A clean PHP API backed by custom page classes: PkdMediahubAssetPage, PkdMediahubCropPage, and PkdMediahubCollectionPage

Before you install

Check that your environment meets the requirements:

  • ProcessWire 3.0.165 or later
  • PHP 8.0 or later
  • AdminThemeUikit active
  • $config->usePageClasses = true set in site/config.php

The usePageClasses line is the one most likely to be missing. MediaHub uses custom page classes for its asset, crop, and collection pages, so this has to be in place before you install. If it's not already there, add it to site/config.php and you're good to go.

A note on the module structure

MediaHub is split into three ProcessWire modules (a core, an admin process, and an inputfield) but you only install MediaHub. ProcessWire automatically installs the other two (ProcessMediaHub and InputfieldMediaHub) in dependency order. The Installation page has the full details.