Proposed API Additions for ProcessWire Page Reference Fields

[BernhardBaumrock]

Background

Currently, ProcessWire's Page Reference fields can return different types (Page object, PageArray, or null) depending on the field's configuration and content. This can lead to inconsistent handling in templates and require type checking or conversion.

Proposed Additions

1. getPageOrFalse('field_name'): Returns a single Page object or false.
2. getPageOrNullpage('field_name'): Returns a single Page object or a NullPage.
3. getPageArray('field_name'): Always returns a PageArray, even for single-page references.

Benefits

1. Consistency: Provides predictable return types, reducing the need for type checking.
2. Simplicity: Allows for cleaner, more straightforward code in templates or modules.
3. Flexibility: Offers different methods to suit various coding styles and use cases.

Use Cases

• Simplifying conditional checks for single-page references
• Ensuring consistent iteration over page references, whether single or multiple
• Reducing boilerplate code for handling different field configurations

Examples

// Single value with simple conditional
$p = $page->getPageOrFalse('my_page_ref_field');
if($p) {
    // Use $p as a Page object
}

// Single value using NullPage pattern
$p = $page->getPageOrNullpage('my_page_ref_field');
if($p->id) {
    // Use $p as a non-null Page object
}

// Consistent array handling
$items = $page->getPageArray('my_page_ref_field');
foreach($items as $item) {
    // Always iterates, even for single-page references
}

These additions would improve code readability, reduce errors related to unexpected types, and provide developers with more intuitive ways to work with Page Reference fields, regardless of their configuration.

[jlahijani]

Related forum thread: https://processwire.com/talk/topic/30358-single-page-select-value-type-which-do-you-prefer/

[teppokoivula]

This request makes sense from developer experience point of view, but adding this as a Page object method doesn’t feel quite right. Shouldn’t it be a method of the field or field value?

Page fields are a common one, but strictly from API design point of view I don’t think that methods specific to individual fieldtypes should be added to the Page class. That’s just my opinion of course.

Additionally I’m seeing some overlap with recent syntax additions here: https://github.com/processwire/processwire/blob/3cc76cc886a49313b4bfb9a1a904bd88d11b7cb7/wire/core/Page.php#L881:L889. With those we already have a way to always get iterable or singular value, at least.

[BernhardBaumrock]

Thx @teppokoivula I'll close this request.

I have been the one requesting the .first and [] syntax for page reference fields (processwire/processwire-issues#1795) but somehow I was not able to get the results that I wanted when adding this request. Maybe it was too late at that day :)

[teppokoivula]

As an afterthought: if a method based approach was preferred (it does have some merits compared to selector string with brackets — such as as improved editor support), we could also consider something slightly less opinionated.

For an example:

• Instead of $page->getPageOrFalse('field_name') we could have $page->getSingleOrFalse('field_name')
• Instead of $page->getPageOrNullpage('field_name') we could have $page->getSingleOrNullpage (or perhaps $page->getSingleOrNullObject or something along those lines)
• Instead of $page->getPageArray('field_name') we could have $page->getMulti('field_name') or perhaps $page->getIterable('field_name') or $page->getArrayObject('field_name')

This would at least get rid of what I considered "bad design", e.g. methods specific to single fieldtype being added to the Page class. And they could work for files and other similar types as well, so we wouldn't need separate $page->getFileOrFalse('field_name') etc.

Anyway, just wanted to say that this idea is not without it's merits :)

[BernhardBaumrock]

@teppokoivula thx for the update. Very good suggestions :) But still I think that it's the best to close this and stick with [] and .first