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.

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.

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, Tags, 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.