MediaHub 1.19: library organisation and findRaw performance

MediaHub 1.19 brings two main themes together: a comprehensive refresh of how the library is organised for editors, and a brand-new high-performance read API for template developers who need asset data at scale.

On the editor side, favourites, labels, collections, filter pills, drag-and-drop assignment, and a calmer grid layout make day-to-day library work faster and clearer. On the developer side, findRaw(), findRawStream(), and the ->raw() shortcut return asset metadata as plain PHP arrays instead of fully hydrated ProcessWire pages, built for galleries, JSON endpoints, sitemaps, and exports where result sets can grow large.

Also in this release: direct file upload in MediaHub fields on the page editor, crop-editor polish on field cards, and improved SVG display in grid and masonry views. Nothing in 1.19 is breaking. Existing foreach ($page->gallery as $asset) code continues to work exactly as before; findRaw is purely additive.

Library organisation

The library sidebar has been given a refresh and is now the control centre for how you browse and organise assets. Three quick filters at the top each show a live count:

• All Assets: your default library view, with every asset in one place. Use it to start fresh or jump back when a label, collection, or time filter has narrowed the grid.
• Favourites: only assets you have starred site-wide. Handy when you keep a shortlist of go-to images (hero shots, approved brand assets, work-in-progress picks) without building a collection for each.
• Recently Added: assets uploaded within a time range you choose (last 24 hours, last 7 days, and other presets). Useful after a bulk upload or when you need to review or tag what landed on the site lately.

When a filter is active, a pill appears below the toolbar with a one-click × to clear it, and the context bar shows a breadcrumb-style trail so you always know where you are (for example All Assets › Labels: Dublin (4) ×).

Favourites

Every asset can be starred site-wide. Use the heart on the asset detail page, the Favourite entry in a tile's ⋯ context menu, or drag selected tiles onto Favourites in the sidebar to favourite several assets at once. Open the Favourites quick filter to see only starred items.

Labels

Labels get their own section in the sidebar with a count beside each name. Click a label to filter the library; drag selected assets onto a label row to assign that label in bulk. Create a new label from the + button in the section header, or use the ⋯ menu on a label row to rename or delete it inline.

Collections

Collections still power folder-style organisation, now with a modal create dialog that supports optional nesting under an existing collection. Collection and label filters are mutually exclusive: picking one clears the other so the view stays predictable. Assign assets by dragging tiles onto a collection row in the sidebar, or use the per-asset Collections flyout from the tile menu when you need to tick several memberships at once.

Recently Added

Recently Added is a great shortcut to see your newest assets. But how recent is recent? Open the three-dot context menu on the row to pick a time range (last 24 hours, last 7 days, and other presets), with counts updated as you go.

Calmer grid and SVG display

Grid view now caps at five columns on extra-wide screens (previously six), giving thumbnails more breathing room and matching the rhythm of masonry view. SVG assets display at natural proportions: contained with padding in grid view, full card width with padding in masonry view, and without the scale-zoom hover effect used on raster tiles so vector artwork stays visually consistent.

Direct upload in MediaHub fields

This is another move towards making MediaHub input field aligned with the default images/file field.

Editors can add assets without having to open the library first. You can drag assets onto any MediaHub field on a page edit screen, or click Upload beside Media Hub in the field toolbar.

Uploads use the same validation as Setup → Media Hub → Upload; new cards appear immediately with crop, focus, and edit actions. A per-field Direct file upload setting (enabled by default) lets you turn this off for strictly curated fields where editors should only pick existing library assets.

Crop editor and field UX

Crop assets placed into a field now show a Crop button on the card and in the edit drawer, opening the unified editor in adjust mode against the master image. Crop filenames can be renamed from the field drawer or the asset detail crops panel; embed URLs stay in sync. The crop editor's dismiss control is labelled Close, and the focus point toggle is hidden in adjust mode so you cannot accidentally change the master image while repositioning a crop.

Lightweight asset retrieval (findRaw)

Early concept / beta (phase 1). findRaw is in 1.19 and fully documented, but treat it as a first pass: the API shape and opt-in fields may still change as real-world use comes in. If you wire it into a project, especially for large lists or exports, please let me know how you get on.

If you've built a gallery that loops $page->gallery as $asset and only needs URLs, dimensions, alt text, labels, or pre-generated crop URLs, you've probably noticed the cost climb as the asset count grows. Each iteration loads a full asset page (and often fires extra queries for image metadata). That pattern is fine for modest lists; it becomes painful for JSON APIs, sitemaps, and export jobs at hundreds or thousands of rows.

1.19 adds a read-only parallel API:

• $page->gallery->raw([...]): shortcut on any MediaHub field value
• $mediaHub->findRaw($source, [...]): field value, selector string, ID list, or collection
• $mediaHub->findRawStream($source, [...]): same row shape, one row at a time for unbounded exports

On a benchmark fixture with 1,000 image assets, findRaw() was roughly 6.7× faster wall time and fired 251× fewer database queries than the standard object loop. The headline gain is not memory alone. It is moving from query count that grows with every asset to a small fixed number of queries regardless of how many rows you return.

Opt-in fields include focus point, labels, collections, favourites, and per-reference overrides. Embedded crops support a library, field, or best resolution chain. Keyset pagination via afterId suits large exports better than offset paging at scale. Multi-language sites can force a language in options when needed.

findRaw never auto-generates missing crops on the fly. Plan ahead with upload automation, the autoGeneratePresetsForAsset hook, or ensureCropImage() on paths that are not performance-critical so crops exist before you read them with findRaw.

Keep using the object API when you need $asset->image()->size(), on-demand crop generation, usage analytics, or writes. The two APIs are designed to work together: findRaw on hot read paths, objects everywhere else.

Thanks to David from FlipZoom Media for the inspiration and implementation of this feature.

Upgrading

No database migration is required for 1.19. The site-wide favourite capability is installed automatically on upgrade (idempotent, safe to re-run). Template code you wrote for the object API does not need changes unless you choose to adopt findRaw for performance.

Docs search

Not part of 1.19, but worth a mention while you're here: the MediaHub documentation now has search. As the product grows and the docs expand, I hope you don't spend long stretches in them. Most of the time you'd rather be building. When you do need an answer, though, you should be able to find it quickly. Use the search box in the docs sidebar to jump to the right page or section without clicking through the nav tree.

Download

MediaHub 1.19 is available from the downloads page. The full list of changes is in the changelog. Editor workflows are covered under The Admin and Labels; the findRaw API is documented on the findRaw docs page.