PageFinder

find($selectors, $options)

Main method. Accepts a selector string, array, or Selectors object, builds the SQL query, executes it, and returns matching data. The return value depends on the returnVerbose, returnParentIDs, returnTemplateIDs, and returnAllCols options — by default, an array of arrays containing id, parent_id, templates_id, and score keys.

// Default: returns verbose array like:
// [ ['id' => 1234, 'parent_id' => 1000, 'templates_id' => 50, 'score' => 0], ... ]
$rows = $finder->find('template=blog-post, sort=-created, limit=10');

// Return a simple array of page IDs
$ids = $finder->find('template=blog-post, limit=10', ['returnVerbose' => false]);

// Return only the DatabaseQuerySelect object without executing it
$query = $finder->find('template=blog-post', ['returnQuery' => true]);
echo $query->getQuery(); // inspect the generated SQL

Throws PageFinderException on database errors and PageFinderSyntaxException on selector syntax errors.

findIDs($selectors, $options)

Convenience wrapper around find() that returns a simple array of page IDs (no parent, template, or score data).

$ids = $finder->findIDs('parent=/about/, template=staff-member');
// [1023, 1024, 1025, ...]

findVerboseIDs($selectors, $options)

Returns an array of all columns from the pages table, indexed by page ID. Supports joining additional fields, sortfields, child counts, page paths, and Unix timestamps via options. (3.0.153+

// Return all pages-table columns indexed by page ID
$rows = $finder->findVerboseIDs('template=article, limit=10');

// [ 1234 => ['id'=>1234, 'name'=>'hello-world', 'status'=>1, ...], ... ]

// Join additional custom fields and the sortfield column
$rows = $finder->findVerboseIDs('template=article, limit=10', [
    'joinFields' => ['headline', 'summary'], // join these field tables
    'joinSortfield' => true,                  // include pages_sortfields.sortfield
    'getNumChildren' => true,                 // include numChildren per page
    'unixTimestamps' => true,                 // return dates as Unix timestamps
]);

findParentIDs($selectors, $options)

Returns an array of parent IDs for each matched page (duplicates removed via GROUP BY). Requires returnVerbose=false.

$parentIDs = $finder->findParentIDs('template=product, limit=100');

findTemplateIDs($selectors, $options)

Returns an array of pageID => templateID pairs. (3.0.152+

$pairs = $finder->findTemplateIDs('parent=/blog/');
// [ 1234 => 50, 1235 => 51, ... ]

count($selectors, $options)

Returns the total number of matching pages without loading page data. Uses COUNT(*) by default rather than SQL_CALC_FOUND_ROWS, making it efficient. (3.0.121+

$total = $finder->count('template=blog-post');
$total = $finder->count('template=blog-post, created>today');

The following methods return information about the most recent find() or count() call. Call them only after a find operation.

$ids = $finder->findIDs('template=article, limit=10, start=20');
echo $finder->getTotal(); // e.g. 137
echo $finder->getLimit(); // 10
echo $finder->getStart(); // 20

getTotalTime() (static)

Returns the cumulative execution time (in seconds) for all PageFinder find() operations during the current request. Only accumulates when the testMode option is enabled. (3.0.257+

$finder->find('template=article, limit=10', ['testMode' => true]);
echo PageFinder::getTotalTime(); // e.g. 0.0023

All options are passed as the second argument to find() and related methods. They are merged with the defaults defined in the $defaultOptions property and any $config->PageFinder overrides.

Inclusion and access control

Query shape and return type

returnAllColsOptions sub-options

These are nested inside returnAllColsOptions when passed to find(). When using findVerboseIDs(), they may also be passed flat at the top level of $options — findVerboseIDs() automatically moves them into returnAllColsOptions internally.

Pagination and totals

ID-based cursor control

Sorting and misc

PageFinder extends Wire, so all of its ___-prefixed methods are hookable. The most commonly hooked methods:

Example: handle unknown field names

/**
 * Map 'region' to a Page reference field named 'geographic_region'
 */
$wire->addHookAfter('PageFinder::getQueryUnknownField', function($event) {
    $fieldName = $event->arguments(0); // string
    $data = $event->arguments(1);      // array

    if($fieldName === 'region') {
        $field = $event->wire('fields')->get('geographic_region');
        if($field) $event->return = $field; // map to a real Field object
    }
});

Example: adjust access-control WHERE clause

/**
 * Allow access to products template for all users
 */
$wire->addHookAfter('PageFinder::getQueryAllowedTemplatesWhere', function($event) {
    /** @var DatabaseQuerySelect $query */
    $query = $event->arguments(0);
    $where = $event->arguments(1); // string

    // Append additional conditions
    $event->return = $where;
});

PageFinder throws two exception types:

try {
    $ids = $finder->findIDs('some-invalid@selector');
} catch(PageFinderSyntaxException $e) {
    echo "Syntax error: " . $e->getMessage();
} catch(PageFinderException $e) {
    echo "Find error: " . $e->getMessage();
}

The syntaxError($message) method is the public entry point that throws PageFinderSyntaxException. You can call it from hooks.

• How to get an instance: new PageFinder() or $pages->getPageFinder() to get the instance used internally by Pages.

• Site-wide option overrides via $config->PageFinder: You can permanently override any default option by setting $config->PageFinder to an array in site/config.php. These overrides are merged before per-call options, so per-call options still win.

  // site/config.php — always run in testMode to accumulate timing data
  $config->PageFinder = ['testMode' => true];

• Page status filtering is automatic. Every find() call modifies the selectors to add a status < statusHidden condition by default. Use include=hidden, include=unpublished, include=trash, include=all in the selector, or the corresponding findHidden, findUnpublished, findTrash, findAll options to relax the restriction.

• Access control is on by default. Non-superusers see only templates they have view access to. Disable with check_access=0 in the selector (must be separate from OR conditions) or findAll=true.

• Return values are raw data, not Page objects. PageFinder returns arrays of IDs or row arrays. The Pages class turns these into Page and PageArray objects. If you need Page objects, use $pages->find() instead.

• Sub-selectors and OR groups. PageFinder handles embedded selectors [...] and OR groups (...) by recursively executing sub-queries to resolve page IDs, then injecting them into the main query. See Selectors for syntax details.

• Fieldtype-specific query building. For each custom field, PageFinder delegates to the Fieldtype's getMatchQuery() method, passing a PageFinderDatabaseQuerySelect (an abstract subclass of DatabaseQuerySelect) that carries the originating Field, Selector, and PageFinder instance as properties. This allows fieldtypes to build their own joins and WHERE conditions.

• Source file: wire/core/PageFinder/PageFinder.php (also Exceptions.php and PageFinderDatabaseQuerySelect.php in the same directory)