Feature request: hookable ref-page resolver for image fields (RPB / non-textarea use cases)

[inreti-sb]

Problem

Image Library's "Used in" tracking currently only covers images embedded in textarea/CKEditor fields (via Insert from Library). Images stored in FieldtypeImage fields — whether on regular content pages or on RockPageBuilder block child pages — are not indexed and show up as "unused" even when actively in use.

On a site with ~4700 images almost exclusively managed via image fields (gallery pages, news articles, RPB blocks), the "Used in" column is effectively empty.

RPB makes this especially difficult

RockPageBuilder stores block content on child pages with auto-generated templates named rockpagebuilderblock-*. Each block page carries its images in image fields (e.g. rpb_gallery_images, rpb_hero_image). These block pages have no public URL — the relevant page for editors is the parent content page that contains the block.

So for RPB, tracking image fields alone is not enough: the ref_page_id must be resolved from the block page up to the first non-block ancestor to produce a useful "Used in" reference.

Proposed solution

Two-step approach:

1. Index images in FieldtypeImage fields

Extend scanUsage() (or add a parallel scan) to also index images stored in image fields, not just textarea embeds. Default behaviour: ref_page_id = page_id (the page that owns the image field is the usage reference).

This already helps all sites using image fields without CKEditor embeds.

2. Hookable ref-page resolver

Expose a hookable method — e.g. resolveRefPageId(Page $imagePage): int — that returns the ref_page_id for a given image-owning page. The default implementation returns $imagePage->id. Third-party code (RPB integrations, custom modules) can hook into it to remap block pages to their content page:

// In site/ready.php or a dedicated RPB integration module:
$wire->addHookAfter('ProcessImageLibrary::resolveRefPageId', function(HookEvent $event) {
    $page = $event->arguments(0);
    if (strncmp((string) $page->template->name, 'rockpagebuilderblock-', 21) !== 0) return;
    $ref = $page->parent;
    while ($ref->id && strncmp((string) $ref->template->name, 'rockpagebuilderblock-', 21) === 0) {
        $ref = $ref->parent;
    }
    if ($ref->id) $event->return = $ref->id;
});

This keeps the module free of RPB-specific knowledge while making it extensible for the growing RPB community.

Current workaround

We implemented a workaround via hooks in site/ready.php that:

• uses SQL bulk-inserts (INSERT IGNORE) into process_imagelibrary_usage directly
• hooks Pages::saved for incremental updates
• hooks ProcessImageLibrary::autoMaintenance (After) to re-insert rows after pruneOrphanedUsageRows() removes them (since our ref_page_id values are not in usageCandidatePageIds())

The maintenance re-insertion workaround in particular feels fragile — it would be much cleaner if image-field rows survived pruning natively or if usageCandidatePageIds() was extended/hookable.

Environment

• ProcessWire 3.0.255, PHP 8.4
• Image Library 1.1.1
• RockPageBuilder (current)

[frameless-at]

Hi Sebastian,

Thanks for the detailed report and for digging into the internals. We discussed this internally and tested it, and I think the approach in the issue is aimed at the wrong layer. Let me explain, because the distinction matters.

Image-field images are not invisible – they're already fully indexed.
The library table is built from every FieldtypeImage field on every eligible template, including infrastructure pages from other modules. So an image in rpb_gallery_images, rpb_hero_image, a normal images field, or a MediaHub asset field already appears as a row, with its Page and Field columns filled, and byte-identical placements are grouped in the duplicates cluster. In the first screenshot the same file (the filename does not matter) shows up on three pages/fields – pkd_mediahub_image, title_image, images – all surfaced, with the "3" cluster badge. Nothing is missing there.

"Used in" answers one narrow question: where is this image embedded in a rich-text (CKEditor/TinyMCE) field? That's a URL reference to a file that physically lives on another page – the invisible, fragile usage that breaks on delete/rename. It is not "where does this image physically sit." The README says as much: "usage that's invisible from the image field the file lives in."

The second screenshot shows both facts coexisting correctly for the same image: three image-field placements (Page/Field/duplicates), and one genuine rich-text embed (page: "test", field: "body") in the Used-in dialog. Those are two different relationships and the module keeps them apart on purpose.

Why indexing image fields into "Used in" would be wrong.
An image in an image field is a physical copy owned by that page (the file lives in that page's assets/files// folder). A rich-text embed is a reference to a file owned elsewhere. Folding image-field placements into "Used in" would merge "this page owns a copy" with "this page references a file owned elsewhere" — and that's exactly what makes your current workaround fragile: you're writing ownership facts into the reference table, then fighting pruneOrphanedUsageRows() (which, correctly, only keeps rows whose ref_page_id is in the textarea-candidate set). It's the right data in the wrong table.

The part of your request that is genuinely valid.
It's that for pages which aren't the useful editorial target, the Page column points at the wrong page. We already resolve this for repeater/matrix items (the storage item page folds up to its owner content page). RPB blocks are plain child pages, not repeaters, so they slip through — the Page link lands on the block child page instead of the parent content page. Same class of problem for MediaHub: the id is right, but the link goes to page/edit instead of the MediaHub asset screen.

What we built.
A hookable ___resolvePageRef(Page $displayPage, Page $storagePage, array $row) that produces the Page-column reference (page id, title, url, edit url, name). Default = current behaviour, so nothing changes unless you hook it. It keeps the module free of any 3rd party module knowledge while letting integrations retarget the reference.

We're currently testing MediaHub, which is an analogous environment (images on their own infrastructure pages with a non-standard editor), so we used it as the proof of concept — and it works: the Page link now goes to …/setup/media-hub/asset/?id= instead of .../page/edit/?id=

For RPB, the hook in site/ready.php is:

$wire->addHookAfter('ProcessImageLibrary::resolvePageRef', function(HookEvent $e) {
    $p = $e->arguments(1); // storage page
    if (strncmp((string) $p->template->name, 'rockpagebuilderblock-', 21) !== 0) return;
    $owner = $p->parent;
    while ($owner->id && strncmp((string) $owner->template->name, 'rockpagebuilderblock-', 21) === 0) {
        $owner = $owner->parent;
    }
    if (!$owner->id) return;
    $e->return = [
        'pageId' => $owner->id,
        'title'  => (string) $owner->title,
        'url'    => (string) $owner->url,
        'editUrl'=> (string) $owner->editUrl,
        'name'   => (string) $owner->name,
    ];
});

That's the same parent-walk you already wrote, but at a supported seam – no direct SQL into process_imagelibrary_usage, and nothing for the maintenance pass to prune away.

One honest limitation: this resolves the Page column link and title (display side). Sorting/filtering still key off the storage page's cached title. For MediaHub that's a non-issue; for RPB it means the link/title show the parent while sort still groups by the block page. If owner-level sorting turns out to matter for RPB, that's a larger, separate change we can look at based on demand.

The change lives on the branch feature/ref-resolver (repo frameless-at/ProcessImageLibrary). If you point our GitSync module (or a plain git checkout feature/ref-resolver) at that branch, you'll get the hookable resolvePageRef(); then drop the RPB hook above into site/ready.php and the "Used in" / usage-table workaround can go. I'd really appreciate your feedback from the ~4700-image RPB site – whether the Page column now resolves to the right content page, and whether anything else feels off – before we merge it into a release.

Cheers, Mike

[inreti-sb]

Hi Mike,

thanks a lot for the extension in general, the clarification and for the quick turnaround with a working feature!

We adopted it from feature/ref-resolver and got it running for RPB. One thing worth reporting back, since it affects whether your suggested snippet works out of the box for other installations too:

The parent-walk assumption doesn't hold for our RPB setup. In RPB, rockpagebuilderblock-* pages are not children of the content page that uses them — they all live flat under one central container page (rockpagebuilderblocks). So $p->parent never reaches the content page; it just returns that container. We had to resolve the reference the other way round: search the FieldtypeRockPageBuilder fields (rpb, rpb_left, rpb_right, …, discovered dynamically by fieldtype rather than hardcoded names) for whichever page currently references the block's id.

A few details that came out of building this, in case they're useful:

• We merged repeater-owner resolution and block-parent resolution into a single loop rather than a one-off repeater step followed by block-only traversal, so a chain that alternates between repeater and block levels any number of times resolves correctly (not just a single hop).
• Our own SQL lookup for the referencing page had a boundary bug worth flagging for anyone copying a similar approach: a plain LIKE '%"id":5%' also matches "id":50 or "id":512. We fetch candidates via LIKE and then verify the exact id via json_decode before accepting a match.
• We noticed pages_meta's own "RockPageBuilder" → "{pageId}-{fieldName}" bookkeeping can go stale — we found a block whose pages_meta entry pointed at a page/field where the live field data no longer referenced it (the block had since been removed/replaced there). We deliberately search only the live field data, never pages_meta, so we don't link to a stale/wrong page — orphaned blocks just show without a Page link instead.

Here the current hook code if useful as a reference for other RPB installations — please let me know if there are optimizations:

Cheers
Sebastian

// (AI-assisted.)
//─────────────────────────────────────────────────────────────────────────────
  // Image Library: resolve RPB block pages to their content page (Page column)
  //
  // Image Library shows the page a given image sits on in the "Page" column.
  // RPB stores images on block sub-pages (rockpagebuilderblock-*) which have no
  // public URL — the column should show the content page instead.
  // Requires Image Library feature/ref-resolver (resolvePageRef hook).
  //
  // Known gap (left as-is by design, as of 2026-07-13): some block images still
  // show an empty Page column, e.g. 6491-maik-esser.jpg and
  // 8537-_pascal-greune.png (gallery block 1677). This isn't a bug here —
  // RPB's own pages_meta bookkeeping (entry "RockPageBuilder" with value
  // "{pageId}-{fieldName}") can go stale without the field itself being
  // updated — the block was presumably later removed/replaced in that
  // rpb*-field. This hook deliberately only searches the LIVE field data
  // (field_rpb*), never pages_meta, so it never links to a stale/wrong page.
  // Consequence: block images that are no longer placed anywhere stay without
  // a Page link instead of showing a wrong one. Verified on production (same
  // behaviour as locally, not a DB-sync artifact).
  // ─────────────────────────────────────────────────────────────────────────────
  if (wire('modules')->isInstalled('ProcessImageLibrary')) {
      // Resolve RPB block pages (and repeater items inside them) to their
      // content page. Block pages live under one central container page, not
      // under the content page — the association is stored exclusively in
      // FieldtypeRockPageBuilder fields (rpb, rpb_left, rpb_right, … —
      // discovered dynamically, not hardcoded).
      //
      // A chain can alternate between repeater and block levels any number of
      // times (repeater item → block → two-columns → block → …), so this uses
      // ONE shared loop instead of a one-off repeater special case up front.
      // Capped at 20 levels as a safeguard against (malformed) circular
    // references in the field data.
    $wire->addHookAfter('ProcessImageLibrary::resolvePageRef', function(HookEvent $e) {
        $pages = $e->wire('pages');
        $db    = $e->wire('database');

        // Determine FieldtypeRockPageBuilder fields by type name (not
        // instanceof, since the class may not be loaded yet when the hook fires).
        $rpbTables = [];
        foreach ($e->wire('fields') as $f) {
            if ((string) $f->type === 'FieldtypeRockPageBuilder') {
                $rpbTables[] = 'field_' . $f->name;
            }
        }
        if (!$rpbTables) return;

        $current    = $e->arguments(1); // storage page
        $wasRpbHop  = false; // only set once at least one level was actually resolved

        for ($i = 0; $i < 20; $i++) {
            $tplName = (string) $current->template->name;

            if (strncmp($tplName, 'repeater_', 9) === 0) {
                // Repeater item: owner page id is encoded in the parent name "for-page-{id}"
                $parentName = (string) $current->parent->name;
                if (!preg_match('/^for-page-(\d+)$/', $parentName, $m)) return;
                $owner = $pages->get('include=all, id=' . (int) $m[1]);
                if (!$owner->id) return;
                $current   = $owner;
                $wasRpbHop = true;
                continue;
            }

            if (strncmp($tplName, 'rockpagebuilderblock-', 21) === 0) {
                // Block page: search all RPB fields for the page referencing it.
                // Exact match via json_decode instead of a bare SQL LIKE hit —
                // "id":5 must not falsely match "id":50 or "id":512.
                $parentId = 0;
                foreach ($rpbTables as $table) {
                    $stmt = $db->prepare("SELECT pages_id, data FROM `{$table}` WHERE data LIKE ?");
                    $stmt->execute(['%"id":' . $current->id . '%']);
                    foreach ($stmt->fetchAll(\PDO::FETCH_ASSOC) as $row) {
                        $entries = json_decode($row['data'], true);
                        if (!is_array($entries)) continue;
                        foreach ($entries as $entry) {
                            if ((int) ($entry['id'] ?? 0) === (int) $current->id) {
                                $parentId = (int) $row['pages_id'];
                                break 2;
                            }
                        }
                    }
                    if ($parentId) break;
                }
                if (!$parentId) return; // orphaned / not currently placed block
                $parent = $pages->get($parentId);
                if (!$parent->id) return;
                $current   = $parent;
                $wasRpbHop = true;
                continue;
            }

            // Reached a regular content page.
            if (!$wasRpbHop) return; // was already a normal page from the start → leave default in place
            $e->return = [
                'pageId'  => $current->id,
                'title'   => (string) $current->title,
                'url'     => (string) $current->url,
                'editUrl' => (string) $current->editUrl,
                'name'    => (string) $current->name,
            ];
            return;
        }
    });
}

[frameless-at]

Hi Sebastian,

perfect, glad it’s running on RPB. Just so it’s clear: we don’t use RockPageBuilder ourselves and don’t know its storage internals, so the parent-walk in our example was a guess and wrong for your setup — your field-lookup resolver is the correct one. We’ve dropped our snippet from the doc block and README and pointed at your implementation here instead.

That’s what the hook is for: it stays builder-agnostic, and the RPB-specific part lives in your site code.

Thanks for taking it all the way to production and writing it up so thoroughly. Much appreciated.

The hook lands in an upcoming release.

Cheers,
Mike