Configuration

Getting there

Go to Modules → Configure → MediaHub in the ProcessWire admin. Settings are split across a few sections.

General settings

Allowed file extensions

A space-separated list of the file extensions editors are permitted to upload. The default is jpg jpeg png gif pdf doc docx xls xlsx pptx csv mp3 mp4 wav. Add or remove extensions to match your project. Note that ProcessWire's own server-level upload restrictions still apply on top of this list, so if an extension is blocked at the PHP level it won't get through regardless of what you set here.

WebP is not included by default because GD (PHP's built-in image library) cannot resize WebP source images. If your server uses Imagick instead, you can add webp manually.

Max upload size (MB)

The per-file size limit. The effective limit is whichever is lower: this setting, or your server's upload_max_filesize PHP ini value. Default is 20 MB.

Max files per upload batch

How many files can be queued in a single upload session. When a user selects more files than this limit, the excess are silently dropped and a dismissible warning banner explains how many were not added and how to adjust the setting. Default is 50. Set to 0 to remove the limit entirely. This is not recommended: selecting hundreds of images at once causes the browser to generate an equal number of object URLs and DOM nodes simultaneously, which can crash the tab.

For large libraries, the recommended workflow is to import in category-sized batches: upload one folder at a time rather than selecting everything at once.

Items per page

How many assets appear per page in the library grid or list. Default is 25. Raise or lower this depending on how many assets your library typically holds and how your server handles pagination queries.

Collections label

What to call the organisational groups in the UI. Options are Collections, Folders, Albums, and Galleries.

This is purely cosmetic. It changes the word displayed in the admin (sidebar title, nav item, button tooltips, bulk-action menus, empty-state messages, table headers, and input placeholders) without affecting the underlying data structure or PHP API. The template API always uses collections(), inCollection(), addToCollection(), etc., regardless of what the label is set to.

Image dimension limits

These settings control what happens when an oversized or undersized image is uploaded.

Setting	What it does
Max width / Max height	Images exceeding these pixel dimensions are resized down at upload time
Reject oversized images	Instead of resizing, refuse images that exceed the max dimensions
Min width / Min height	Images below these dimensions are rejected
Swap dimensions for portrait	Applies max/min limits correctly when the image is taller than it is wide

If you leave max dimensions blank, no upper limit is enforced. Min dimensions are useful for ensuring editors don't upload thumbnails or icons into a library that feeds full-width hero sections.

SVG Support

SVG (Scalable Vector Graphics) uploads are disabled by default. SVG files are text-based and can embed scripts or external references, so MediaHub keeps them off until you explicitly opt in.

Enabling SVG requires Ryan Cramer's FileValidatorSvgSanitizer module. With the sanitiser installed, every uploaded SVG is checked for unsafe content and rewritten before the asset is created. If the sanitiser is missing while Allow SVG uploads is ticked, SVG uploads are refused.

To enable:

1. Install FileValidatorSvgSanitizer from the ProcessWire module directory.
2. In MediaHub module config, open the SVG Support section.
3. Confirm the sanitiser status indicator is green.
4. Tick Allow SVG uploads and save.

Behaviour on SVG assets

Because SVG files are vector (resolution-independent), some MediaHub features do not apply:

• Cropping and focus point are hidden on SVG asset cards and on the SVG asset detail page.
• The Crops API returns null for SVG.
• Upload automation silently skips SVG files when generating preset crops.
• Everything else — rename, alt text, labels, collections, drag-to-reorder in fields, the picker, TinyMCE insertion — works the same as for raster images.

In template code, use $asset->isSvg() and $asset->isRasterImage() to distinguish vector from raster assets. See the Template API.

Crop presets

Nine crop presets are built into MediaHub and are always available:

Label	Key	Ratio
Freeform	freeform	No constraint
Original	original	Matches the image's natural aspect ratio
Square	square	1:1
16:9	16_9	16:9
4:5	4_5	4:5
5:7	5_7	5:7
4:3	4_3	4:3
3:5	3_5	3:5
3:2	3_2	3:2

Adding custom presets

Under Crop Presets in the module config, click Add preset and fill in four fields:

Field	Description	Example
Label	Human-readable name shown in the crop editor	Hero Banner
Key	Used in template code (letters, numbers, underscores only)	hero_banner
Ratio	Width:Height format. Leave blank for freeform.	16:5
Group	Optional group name. Presets with the same group appear together in a collapsible section in the crop editor sidebar.	Social

Custom presets appear alongside the built-in ones in the crop editor and are available in the cropImage(), hasCrop(), and ensureCropImage() API methods using their key.

If a custom preset key collides with a built-in key or another custom key, it is automatically suffixed at runtime (e.g. square_custom) and a warning is logged. Rename the key in module settings to resolve the collision permanently.

Upload automation

Auto-generate crops on upload

Under Upload Automation in the module config, a list of checkboxes shows every crop preset that has a fixed aspect ratio (Freeform is excluded because it has no ratio to calculate a centred crop from). Tick the presets you want generated automatically whenever a new image is uploaded to the library.

When an image is uploaded, MediaHub creates a crop for each checked preset, framed around the asset's focus point when one has been moved from centre, or centred on the image otherwise. The crop is a library-scoped crop page, visible in the asset's Crops section, queryable via cropImage() and ensureCropImage(), and adjustable by an editor at any time. If a crop already exists for a given preset (for example, from a re-upload or a concurrent process), the existing crop is returned and no duplicate is created.

Each checked preset adds one image-processing operation per uploaded file. On shared hosting or when uploading large batches, selecting many presets can slow uploads noticeably. Start with the presets you use most and add more as needed.

Logging

MediaHub can write a log file at site/assets/logs/media-hub.txt, accessible from Setup → Logs in the ProcessWire admin. Logging is off by default from v1.10 onwards. On active sites and especially during imports, the log file grew quickly and added noise to the log viewer.

To enable logging, check Enable logging under the Logging section in module config and save. Verbose logging is most useful during development or when tracking down an unexpected behaviour.

The same section includes a Clear Logs button that resets the log file without you having to access the filesystem directly.

Licensing

The Licensing fieldset on the module config page accepts a Freemius license key (sk_...). On save, the key is validated against the Freemius API and the install is registered. The status is shown inline: activated, invalid format, quota reached, or not registered.

Licensing is entirely optional and non-blocking. An incorrect, expired, or missing license key never prevents the module from loading, saving, or rendering. Every feature works identically regardless of license status.

If you move a site between hosts (e.g. local to production), the license re-registers automatically on the next admin page load. No manual deactivation is needed. Local and development environments (localhost, .local, .test, .dev, .ddev.site, non-standard ports, private IP ranges) are detected automatically and do not consume your production activation quota.

A collapsible privacy note on the config screen explains exactly what data is sent (license key and site URL) and to whom (Freemius). No other data is transmitted.

Permissions

Installation creates a media-hub-admin permission. Only users with this permission can access the Media Hub admin, including the Library, Upload, Labels, Folders, and Import screens.

To grant access:

1. Go to Access → Roles in the ProcessWire admin
2. Edit the role you want to grant access to (e.g. editor)
3. Under Permissions, check media-hub-admin
4. Save

Superusers always have access regardless of this permission.

Note that this controls access to the standalone Media Hub admin. The ability to select MediaHub assets in a page field is controlled by the standard ProcessWire page-edit permissions: if a user can edit a page with a MediaHub field, they can use the picker.

Admin Navigation (v1.16.0)

Two new settings control how MediaHub appears in the ProcessWire admin chrome. Both are optional and disabled by default. The existing Setup → Media Hub entry-point is always available regardless of these settings.

Show MediaHub link in main navigation

Adds a top-level Media Hub entry to the admin top bar, sitting alongside Pages, Setup, Modules, and Access. The dropdown contains the same five items found under Setup → Media Hub: Library, Upload, Folders, Labels, Import.

Useful for editorial teams who live in MediaHub day-to-day and want a one-click entry point. Toggling this off later cleanly removes the top-bar entry, including its sub-pages. The underlying data and module pages are unaffected.

Custom label for the top-level link

Only visible when the option above is enabled. Lets you override what appears in the top bar. Useful in two situations:

• Verbose translations. The localised "Media Hub" string can be long in some languages (Polish Centrum multimedialne, Welsh Canolbwynt y Cyfryngau, German Medien-Hub) and squeeze the top bar layout, especially with several other top-level items already in place.
• Team-specific vocabulary. Some teams use "Media", "Assets", "Library", or "DAM" rather than "Media Hub". 4-10 characters works best given the limited top-bar real estate.

Leave the field blank to use the localised default. The Setup → Media Hub label inside the Setup dropdown is unaffected by this setting.