Cross-Environment Page IDs

The problem

Page IDs in ProcessWire are auto-incremented integers. A page at /blog/categories/products/ might be ID 42 on your local site and ID 187 on production. If your content YAML contains a page reference like id: 42, pushing it to production would link to the wrong page (or no page at all).

How PromptWire resolves it

When you pull a page, every page reference field is exported with both the numeric ID and the path:

blog_categories:
  -
    _pageRef: true
    id: 42
    path: /blog/categories/products/
    _comment: Products @ /blog/categories/products/

When you push, PromptWire resolves each reference using path first. It looks up /blog/categories/products/ on the target site. If that path exists, it uses whatever page ID it has on that site. The numeric id is only used as a fallback for same-environment pushes where the path lookup fails.

What this means in practice

You can pull content from your local site, push it to production, and all page references (categories, tags, parent pages, related content) will resolve correctly as long as the referenced pages exist at the same paths on both sites.

If a referenced page doesn't exist on the target site, the reference will fail to resolve and you'll get a warning. This is intentional: it prevents silent data corruption from dangling references.

Validating references

Before pushing content to a different environment, you can validate that all page references in your local sync files will resolve on the target:

Validate page references against production.

pw_validate_refs scans all synced YAML files and checks whether each referenced path exists on the target site. It reports any references that would fail to resolve.

Repeaters and matrix items

Page references inside repeater and matrix items follow the same resolution logic. Each nested _pageRef entry includes both id and path, and the path is used for cross-environment resolution.