A PageArray is a collection of Page objects in ProcessWire.

Any API function in ProcessWire that is designed to return more than one Page typically returns a PageArray. You can use and iterate a PageArray just like a regular PHP array. However, like other WireArray types, a PageArray has many built in functions to simplify your tasks. These functions are documented in the reference below.

While PHP's array and iteration syntax will work with PageArrays, PHP's library of array functions will not. Instead you should use the built-in functions outlined in the PageArray reference below. You can also convert a PageArray to a regular PHP array just by using it's built in getArray() function (documented below).

API functions that return a PageArray

  • $pages->find()
  • $page->find()
  • $page->children()
  • $page->siblings()
  • $page->parents()
  • Page reference field types, when set to contain more than 1 page.
  • Many built-in PageArray functions, outlined below.

PageArray Reference

Note: in the following reference, $p represents the name of any PageArray variable, so $p as a variable name is not significant.

Getting pages

$p[$key]Returns the instance of the page at the given $key, or null if not set.
$p->$keyReturn the page indexed by $key or null if not found.
$p->get($key)Returns the instance of the page at the given $key, or null if not set.
$p->get("selector")Return the first page that matches the given selector, or null if not found.
$p->find("selector")Return all pages that match the given selector, or a blank PageArray if none found.
$p->getArray()Returns a regular PHP array of all pages in this PageArray.
$p->getKeys()Returns a regular PHP array of all keys used in this PageArray.
$p->getValues()Returns a regular PHP array of all instances used in this PageArray.
$p->getRandom()Returns a single random page from this PageArray.
$p->getRandom($n)Returns $n random pages from this PageArray (contained in a new PageArray).
$p->slice($n)Returns a new PageArray containing a slice of pages from the $n'th page to the end.
$p->slice($n, $limit)  Returns a new PageArray containing a slice of pages starting from the $n'th page and including up to $limit number of pages.
$p->shift()Remove (shift) the first $page from the PageArray and return it.
$p->pop()Pop the last page off of the PageArray and return it.
$p->index($n)Returns a new PageArray containing the page at the given zero-based index.
$p->eq($n)Returns the single page at the given zero-based index, or NULL if it doesn't exist.
$p->first()Returns the first page in the PageArray.
$p->last()Returns the last page in the PageArray.
$p->getNext($page)  Given an page already in the PageArray, return the page that comes after it in this PageArray or NULL if no match.
$p->getPrev($page)Given an page already in the PageArray, return the page that comes before it in this PageArray or NULL if no match.

Setting and modifying pages

$p[] = $pageAdd the given $page.
$p->add($page)Add the given $page.
$p[$key] = $pageAdd the given $page, associating it with index $key.
$p->set($key, $page)Add the given $page, associating it with index $key.
$p->$key = $pageAdd the given $page, associating it with index $key.
$p->import($pages)Given an array or PageArray of pages, add them all.
$p->prepend($page)Prepend the given page to the beginning of the PageArray.
$p->append($page)  Append the given page to the end of the PageArray.
$p->unshift($page)Prepend the given page to the beginning of the PageArray (same as prepend)
$p->shift()Remove (shift) the first $page from the PageArray and return it.
$p->push($page)Push the given page onto the end of the PageArray.
$p->pop()Pop the last page off of the PageArray and return it.
unset($array[$key])  Removes the page with the given $key from the PageArray.
$p->remove($key)Removes the page with the given $key from the PageArray.
$p->remove($page)  Removes the given $page from the PageArray.

Unless otherwise noted, all set/modify/remove functions listed above return reference to the PageArray, enabling you to stack these functions in a fluent interface. 

Checking for pages

$p->count()  Returns the number of pages in this PageArray.
count($a)Returns the number of pages in this PageArray.
$p->has($key)Is the given key part of this PageArray?
$p->has("selector")Does the given selector match any pages in this PageArray?
isset($p[$key])Returns true if the given $key is set with an page.
$p->isValidItem($page)Is the given page a valid type for this PageArray?
$p->isValidKey($key)Is the given $key valid to use for this PageArray?
$p->getItemKey($page)Get the key used by $page or NULL if not available.

Sorting and Filtering

$p->shuffle()  Randomize the order of all the pages in the PageArray.
$p->sort("property")  Sorts the PageArray by the given page property (string). You may also specify the property as "property.subproperty", where property resolves to a Wire derived object, and subproperty resolves to a property within that object. Prepend a minus sign "-" to the property name reverse the sort.
$p->filter("selector")  Reduce the PageArray so that it only contains pages that match the given selector.
$p->not("selector")  Reduce the PageArray so that it only contains pages that don't match the given selector.
$p->reverse()Return a new PageArray containing the pages in reverse order.

Change Tracking

$p->setTrackChanges()Turn on change tracking
$p->setTrackChanges(false)Turn off change tracking
$p->resetTrackChanges()Reset any changes that have been tracked and start tracking again.
$p->resetTrackChanges(false)Reset any changes that have been tracked and stop tracking.
$p->getChanges()Return an array of page keys that have changed while change tracking was on.
$p->getItemsAdded()Return an array of pages that have been added since change tracking was turned on.
$p->getItemsRemoved()Return an array of pages that have been removed since change tracking was turned on.

Miscellaneous

$p->makeBlankItem()Make a new blank page suitable for storage in this PageArray.
$p->makeNew()Make a new blank PageArray of the same type as $p.

Iteration

You can iterate a PageArray just like a regular PHP array.

<?php
foreach($p as $key => $page) {
    echo "$key = $page <br />";
}

Pagination and Selectors

These functions are used internally by ProcessWire and you aren't likely to need these in your typical site development tasks. But they are here if you need them.

$p->getTotal()Get the total number of pages that were found from a $pages->find("selectors, limit=n") operation that led to this PageArray. The number returned may be greater than the number of pages actually in this PageArray instance, and is used for calculating pagination. Whereas $p->count() will always return the number of pages actually in this PageArray instance.
$p->getLimit()Get the number (n) from a "limit=n" portion of a selector that resulted in this PageArray. In pagination, this value represents the max items to display per page. If there was no limit applied, this will return 0.
$p->getStart()Get the number of the starting result that led to this PageArray in pagination. Returns 0 if in the first page of results.
$p->getSelectors()Return the Selectors that led to this PageArray, or null if not set/applicable. Returns an instance of Selectors (WireArray) containing one or more Selector objects.

PageArray as a String

If dereferenced as a string, a PageArray will return a pipe "|" separated list of page IDs present in the PageArray. If the PageArray is blank, it will return a blank string. Lets say that you have a PageArray with pages having the IDs 123, 456, and 78910. The string value would be:

123|456|78910

This behavior is used internally by ProcessWire, but may also have potential value elsewhere.

Additional Notes

Unlike other types of WireArrays, PageArrays can also accept a page ID number to the add() function. If the Page instance referenced by that number is not already loaded, then the PageArray will load it automatically and store it.

Plugin modules may add additional methods to all PageArrays at runtime. An example is the MarkupPageArray module, which adds a render() method to all PageArrays. So calling $p->render() returns an unordered list of HTML5/XHTML markup with links to all the pages in the PageArray, including pagination where applicable. See the MarkupPageArray module for more details and customization options.

See Also

$pages
$page
WireArray

Comments

No comments yet. Be the first to post!

Post a Comment

Your e-mail is kept confidential and not included with your comment. Website is optional.