724 lines
19 KiB
PHP
724 lines
19 KiB
PHP
<?php namespace ProcessWire;
|
|
|
|
/**
|
|
* ProcessWire PageArray
|
|
*
|
|
* PageArray provides an array-like means for storing PageReferences and is utilized throughout ProcessWire.
|
|
*
|
|
* #pw-summary PageArray is a paginated type of WireArray that holds multiple Page objects.
|
|
* #pw-body =
|
|
* **Please see the `WireArray` and `PaginatedArray` types for available methods**, as they are not
|
|
* repeated here, except where PageArray has modified or extended those types in some manner.
|
|
* The PageArray type is functionally identical to WireArray and PaginatedArray except that it is focused
|
|
* specifically on managing Page objects.
|
|
*
|
|
* PageArray is returned by all API methods in ProcessWire that can return more than one page at once.
|
|
* `$pages->find()` and `$page->children()` are common examples that return PageArray.
|
|
*
|
|
* You can create a new PageArray using any of the methods below:
|
|
* ~~~~~
|
|
* // the most common way to create a new PageArray and add a $page to it
|
|
* $a = new PageArray();
|
|
* $a->add($page);
|
|
*
|
|
* // ProcessWire 3.0.123+ can also create PageArray like this:
|
|
* $a = PageArray(); // create blank
|
|
* $a = PageArray($page); // create + add one page
|
|
* $a = PageArray([ $page1, $page2, $page3 ]); // create + add pages
|
|
* ~~~~~
|
|
* #pw-body
|
|
*
|
|
* ProcessWire 3.x, Copyright 2021 by Ryan Cramer
|
|
* https://processwire.com
|
|
*
|
|
* @method string getMarkup($key = null) Render a simple/default markup value for each item #pw-internal
|
|
* @property Page|null $first First item
|
|
* @property Page|null $last Last item
|
|
* @property Page[] $data #pw-internal
|
|
*
|
|
*/
|
|
|
|
class PageArray extends PaginatedArray implements WirePaginatable {
|
|
|
|
/**
|
|
* Reference to the selectors that led to this PageArray, if applicable
|
|
*
|
|
* @var Selectors|string
|
|
*
|
|
*/
|
|
protected $selectors = null;
|
|
|
|
/**
|
|
* Options that were passed to $pages->find() that led to this PageArray, when applicable.
|
|
*
|
|
* Applies only for lazy loading result sets.
|
|
*
|
|
* @var array
|
|
*
|
|
*/
|
|
protected $finderOptions = array();
|
|
|
|
/**
|
|
* Is this a lazy-loaded PageArray?
|
|
*
|
|
* @var bool
|
|
*
|
|
*/
|
|
protected $lazyLoad = false;
|
|
|
|
/**
|
|
* Index of item keys of page_id => data key
|
|
*
|
|
* @var array
|
|
*
|
|
*/
|
|
protected $keyIndex = array();
|
|
|
|
/**
|
|
* Template method that descendant classes may use to validate items added to this WireArray
|
|
*
|
|
* #pw-internal
|
|
*
|
|
* @param mixed $item Item to add
|
|
* @return bool True if item is valid and may be added, false if not
|
|
*
|
|
*/
|
|
public function isValidItem($item) {
|
|
return is_object($item) && $item instanceof Page;
|
|
}
|
|
|
|
/**
|
|
* Validate the key used to add a Page
|
|
*
|
|
* PageArrays are keyed by an incremental number that does NOT relate to the Page ID.
|
|
*
|
|
* #pw-internal
|
|
*
|
|
* @param string|int $key
|
|
* @return bool True if key is valid and may be used, false if not
|
|
*
|
|
*/
|
|
public function isValidKey($key) {
|
|
return ctype_digit("$key");
|
|
}
|
|
|
|
/**
|
|
* Get the array key for the given Page item
|
|
*
|
|
* This method is used internally by the add() and prepend() methods.
|
|
*
|
|
* #pw-internal
|
|
*
|
|
* @param Page $item Page to get key for
|
|
* @return string|int|null Found key, or null if not found.
|
|
*
|
|
*/
|
|
public function getItemKey($item) {
|
|
if(!$item instanceof Page) return null;
|
|
if(!$this->duplicateChecking) return parent::getItemKey($item);
|
|
|
|
// first see if we can determine key from our index
|
|
$id = $item->id;
|
|
if(isset($this->keyIndex[$id])) {
|
|
// given item exists in this PageArray (or at least has)
|
|
$key = $this->keyIndex[$id];
|
|
if(isset($this->data[$key])) {
|
|
$page = $this->data[$key]; /** @var Page $page */
|
|
if($page->id === $id) {
|
|
// found it
|
|
return $key;
|
|
}
|
|
}
|
|
// if this (maybe unreachable) point is reached, then index needs to
|
|
// be rebuilt because either item is no longer here, or has moved
|
|
$this->keyIndex = array();
|
|
foreach($this->data as $key => $page) {
|
|
$this->keyIndex[$page->id] = $key;
|
|
}
|
|
return isset($this->keyIndex[$id]) ? $this->keyIndex[$id] : null;
|
|
} else {
|
|
// page is not present here
|
|
return null;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Does this PageArray use numeric keys only? (yes it does)
|
|
*
|
|
* Defined here to override the slower check in WireArray
|
|
*
|
|
* @return bool
|
|
*
|
|
*/
|
|
protected function usesNumericKeys() {
|
|
return true;
|
|
}
|
|
|
|
/**
|
|
* Per WireArray interface, return a blank Page
|
|
*
|
|
* #pw-internal
|
|
*
|
|
* @return Page
|
|
*
|
|
*/
|
|
public function makeBlankItem() {
|
|
return $this->wire()->pages->newPage();
|
|
}
|
|
|
|
/**
|
|
* Creates a new blank instance of this PageArray, for internal use.
|
|
*
|
|
* #pw-internal
|
|
*
|
|
* @return PageArray
|
|
*
|
|
*/
|
|
public function makeNew() {
|
|
$class = get_class($this);
|
|
/** @var PageArray $newArray */
|
|
$newArray = $this->wire(new $class());
|
|
// $newArray->finderOptions($this->finderOptions());
|
|
if($this->lazyLoad) $newArray->_lazy(true);
|
|
return $newArray;
|
|
}
|
|
|
|
/**
|
|
* Import the provided pages into this PageArray.
|
|
*
|
|
* #pw-internal
|
|
*
|
|
* @param array|PageArray|Page $pages Pages to import.
|
|
* @return PageArray reference to current instance.
|
|
*
|
|
*/
|
|
public function import($pages) {
|
|
if(is_object($pages) && $pages instanceof Page) $pages = array($pages);
|
|
if(!self::iterable($pages)) return $this;
|
|
foreach($pages as $page) $this->add($page);
|
|
if($pages instanceof PageArray) {
|
|
if(count($pages) < $pages->getTotal()) {
|
|
$this->setTotal($this->getTotal() + ($pages->getTotal() - count($pages)));
|
|
}
|
|
}
|
|
return $this;
|
|
}
|
|
|
|
/**
|
|
* Does this PageArray contain the given index or Page?
|
|
*
|
|
* #pw-internal
|
|
*
|
|
* @param Page|int $key Page Array index or Page object.
|
|
* @return bool True if the index or Page exists here, false if not.
|
|
*/
|
|
public function has($key) {
|
|
if(is_object($key) && $key instanceof Page) {
|
|
return $this->getItemKey($key) !== null;
|
|
}
|
|
return parent::has($key);
|
|
}
|
|
|
|
|
|
/**
|
|
* Add one or more Page objects to this PageArray.
|
|
*
|
|
* Please see the `WireArray::add()` method for more details.
|
|
*
|
|
* ~~~~~
|
|
* // Add one page
|
|
* $pageArray->add($page);
|
|
*
|
|
* // Add multiple pages
|
|
* $pageArray->add($pages->find("template=basic-page"));
|
|
*
|
|
* // Add page by ID
|
|
* $pageArray->add(1005);
|
|
* ~~~~~
|
|
*
|
|
* @param Page|PageArray|int $page Page object, PageArray object, or Page ID.
|
|
* - If given a `Page`, the Page will be added.
|
|
* - If given a `PageArray`, it will do the same thing as the `WireArray::import()` method and append all the pages.
|
|
* - If Page `ID`, the Page identified by that ID will be loaded and added to the PageArray.
|
|
* @return $this
|
|
*/
|
|
public function add($page) {
|
|
|
|
if($this->isValidItem($page)) {
|
|
parent::add($page);
|
|
|
|
} else if($page instanceof PageArray || is_array($page)) {
|
|
return $this->import($page);
|
|
|
|
} else if(ctype_digit("$page")) {
|
|
$page = $this->wire()->pages->get("id=$page");
|
|
if($page->id) parent::add($page);
|
|
}
|
|
return $this;
|
|
}
|
|
|
|
/**
|
|
* Get one or more random pages from this PageArray.
|
|
*
|
|
* If one item is requested, the item is returned (unless $alwaysArray is true).
|
|
* If multiple items are requested, a new WireArray of those items is returned.
|
|
*
|
|
* #pw-internal
|
|
*
|
|
* @param int $num Number of items to return. Optional and defaults to 1.
|
|
* @param bool $alwaysArray If true, then method will always return a container of items, even if it only contains 1.
|
|
* @return Page|PageArray Returns value of item, or new PageArray of items if more than one requested.
|
|
*/
|
|
public function getRandom($num = 1, $alwaysArray = false) {
|
|
return parent::getRandom($num, $alwaysArray);
|
|
}
|
|
|
|
/**
|
|
* Get a quantity of random pages from this PageArray.
|
|
*
|
|
* Unlike getRandom() this one always returns a PageArray (or derived type).
|
|
*
|
|
* #pw-internal
|
|
*
|
|
* @param int $num Number of items to return
|
|
* @return PageArray|WireArray New PageArray instance
|
|
*
|
|
*/
|
|
public function findRandom($num) {
|
|
return parent::findRandom($num);
|
|
}
|
|
|
|
/**
|
|
* Get a slice of the PageArray.
|
|
*
|
|
* Given a starting point and a number of items, returns a new PageArray of those items.
|
|
* If $limit is omitted, then it includes everything beyond the starting point.
|
|
*
|
|
* #pw-internal
|
|
*
|
|
* @param int $start Starting index.
|
|
* @param int $limit Number of items to include. If omitted, includes the rest of the array.
|
|
* @return PageArray|WireArray New PageArray instance
|
|
*
|
|
*/
|
|
public function slice($start, $limit = 0) {
|
|
return parent::slice($start, $limit);
|
|
}
|
|
|
|
/**
|
|
* Returns the item at the given index starting from 0, or NULL if it doesn't exist.
|
|
*
|
|
* Unlike the index() method, this returns an actual item and not another PageArray.
|
|
*
|
|
* #pw-internal
|
|
*
|
|
* @param int $num Return the nth item in this WireArray. Specify a negative number to count from the end rather than the start.
|
|
* @return Page|Wire|null Returns Page object or null if not present
|
|
*
|
|
*/
|
|
public function eq($num) {
|
|
return parent::eq($num);
|
|
}
|
|
|
|
/**
|
|
* Returns the first item in the PageArray or boolean FALSE if empty.
|
|
*
|
|
* #pw-internal
|
|
*
|
|
* @return Page|bool
|
|
*
|
|
*/
|
|
public function first() {
|
|
return parent::first();
|
|
}
|
|
|
|
/**
|
|
* Returns the last item in the PageArray or boolean FALSE if empty.
|
|
*
|
|
* #pw-internal
|
|
*
|
|
* @return Page|bool
|
|
*
|
|
*/
|
|
public function last() {
|
|
return parent::last();
|
|
}
|
|
|
|
/**
|
|
* Set the Selectors that led to this PageArray, if applicable
|
|
*
|
|
* #pw-internal
|
|
*
|
|
* @param Selectors|string $selectors Option to add as string added in 3.0.142
|
|
* @return $this
|
|
*
|
|
*/
|
|
public function setSelectors($selectors) {
|
|
if(is_string($selectors) || $selectors instanceof Selectors || $selectors === null) {
|
|
$this->selectors = $selectors;
|
|
}
|
|
return $this;
|
|
}
|
|
|
|
/**
|
|
* Return the Selectors that led to this PageArray, or null if not set/applicable.
|
|
*
|
|
* Use this to retrieve the Selectors that were used to find this group of pages,
|
|
* if dealing with a PageArray that originated from a database operation.
|
|
*
|
|
* ~~~~~
|
|
* $products = $pages->find("template=product, featured=1, sort=-modified, limit=10");
|
|
* echo $products->getSelectors(); // outputs the selector above
|
|
* ~~~~~
|
|
*
|
|
* @param bool $getString Specify true to get selector string rather than Selectors object (default=false) added in 3.0.142
|
|
* @return Selectors|string|null Returns Selectors object if available, or null if not. Always return string if $getString argument is true.
|
|
*
|
|
*/
|
|
public function getSelectors($getString = false) {
|
|
if($getString) return (string) $this->selectors;
|
|
if($this->selectors === null) return null;
|
|
if(is_string($this->selectors)) $this->selectors = $this->wire(new Selectors($this->selectors));
|
|
return $this->selectors;
|
|
}
|
|
|
|
/**
|
|
* Filter out Pages that don't match the selector.
|
|
*
|
|
* This is applicable to and destructive to the WireArray.
|
|
*
|
|
* @param string|Selectors|array $selectors AttributeSelector string to use as the filter.
|
|
* @param bool|int $not Make this a "not" filter? Use int 1 for "not all". (default is false)
|
|
* @return PageArray|WireArray reference to current [filtered] PageArray
|
|
*
|
|
*/
|
|
protected function filterData($selectors, $not = false) {
|
|
if(is_string($selectors) && $selectors[0] === '/') $selectors = "path=$selectors";
|
|
return parent::filterData($selectors, $not);
|
|
}
|
|
|
|
/**
|
|
* Filter out pages that don't match the selector (destructive)
|
|
*
|
|
* #pw-internal
|
|
*
|
|
* @param string $selector AttributeSelector string to use as the filter.
|
|
* @return PageArray|PaginatedArray|WireArray reference to current PageArray instance.
|
|
*
|
|
*/
|
|
public function filter($selector) {
|
|
return parent::filter($selector);
|
|
}
|
|
|
|
/**
|
|
* Filter out pages that don't match the selector (destructive)
|
|
*
|
|
* #pw-internal
|
|
*
|
|
* @param string $selector AttributeSelector string to use as the filter.
|
|
* @return PageArray|PaginatedArray|WireArray reference to current PageArray instance.
|
|
*
|
|
*/
|
|
public function not($selector) {
|
|
return parent::not($selector);
|
|
}
|
|
|
|
/**
|
|
* Like the base get() method but can only return Page objects (whether Page or NullPage)
|
|
*
|
|
* @param int|string|array $key Provide any of the following:
|
|
* - Key of Page to retrieve.
|
|
* - A selector string or selector array, to return the first item that matches the selector.
|
|
* - A string containing the "name" property of any Page, and the matching Page will be returned.
|
|
* @return Page|NullPage
|
|
* @since 3.0.162
|
|
* @see WireArray::get()
|
|
*
|
|
*/
|
|
public function getPage($key) {
|
|
$value = $this->get($key);
|
|
return $value instanceof Page ? $value : $this->wire()->pages->newNullPage();
|
|
}
|
|
|
|
/**
|
|
* Find all pages in this PageArray that match the given selector (non-destructive)
|
|
*
|
|
* This is non destructive and returns a brand new PageArray.
|
|
*
|
|
* #pw-internal
|
|
*
|
|
* @param string $selector AttributeSelector string.
|
|
* @return PageArray|WireArray New PageArray instance
|
|
* @see WireArray::find()
|
|
*
|
|
*/
|
|
public function find($selector) {
|
|
return parent::find($selector);
|
|
}
|
|
|
|
/**
|
|
* Same as find() method, but returns a single Page rather than PageArray or FALSE if empty.
|
|
*
|
|
* #pw-internal
|
|
*
|
|
* @param string $selector
|
|
* @return Page|bool
|
|
* @see WireArray::findOne()
|
|
*
|
|
*/
|
|
public function findOne($selector) {
|
|
return parent::findOne($selector);
|
|
}
|
|
|
|
/**
|
|
* Same as find() or findOne() methods, but always returns a Page (whether Page or NullPage)
|
|
*
|
|
* @param string $selector
|
|
* @return Page|NullPage
|
|
* @since 3.0.162
|
|
*
|
|
*/
|
|
public function findOnePage($selector) {
|
|
$value = parent::findOne($selector);
|
|
return $value instanceof Page ? $value : $this->wire()->pages->newNullPage();
|
|
}
|
|
|
|
/**
|
|
* Get Page from this PageArray having given name, or return NullPage if not present
|
|
*
|
|
* @param string $name
|
|
* @return NullPage|Page
|
|
* @since 3.0.162
|
|
*
|
|
*/
|
|
public function getPageByName($name) {
|
|
return $this->getPageByProperty('name', $name, true);
|
|
}
|
|
|
|
/**
|
|
* Get Page from this PageArray having given ID, or return NullPage if not present
|
|
*
|
|
* @param int $id
|
|
* @return NullPage|Page
|
|
* @since 3.0.162
|
|
*
|
|
*/
|
|
public function getPageByID($id) {
|
|
$id = (int) $id;
|
|
if(isset($this->keyIndex[$id])) {
|
|
$k = $this->keyIndex[$id];
|
|
if(isset($this->data[$k]) && $this->data[$k]->id === $id) return $this->data[$k];
|
|
}
|
|
return $this->getPageByProperty('id', (int) $id, true);
|
|
}
|
|
|
|
/**
|
|
* Get first found Page object matching property/value, or return NullPage if not present in this PageArray
|
|
*
|
|
* #pw-internal
|
|
*
|
|
* @param string $property Name of page property or field
|
|
* @param string|mixed $value Value to match
|
|
* @param bool $strict Match value with strict type enforcement? (default=false)
|
|
* @return Page|NullPage
|
|
* @since 3.0.162
|
|
*
|
|
*/
|
|
public function getPageByProperty($property, $value, $strict = false) {
|
|
$foundPage = null;
|
|
foreach($this->data as $item) {
|
|
if($strict) {
|
|
if($item->get($property) === $value) $foundPage = $item;
|
|
} else {
|
|
if($item->get($property) == $value) $foundPage = $item;
|
|
}
|
|
if($foundPage) break;
|
|
}
|
|
return $foundPage ? $foundPage : $this->wire()->pages->newNullPage();
|
|
}
|
|
|
|
/**
|
|
* Prepare selectors for filtering
|
|
*
|
|
* Template method for descending classes to modify selectors if needed
|
|
*
|
|
* @param Selectors $selectors
|
|
*
|
|
*/
|
|
protected function filterDataSelectors(Selectors $selectors) {
|
|
$disallowed = array('include', 'check_access', 'checkAccess');
|
|
foreach($selectors as $selector) {
|
|
if(in_array($selector->field(), $disallowed)) {
|
|
$selectors->remove($selector);
|
|
}
|
|
}
|
|
parent::filterDataSelectors($selectors);
|
|
}
|
|
|
|
/**
|
|
* Get the value of $property from $item
|
|
*
|
|
* Used by the WireArray::sort method to retrieve a value from a Wire object.
|
|
* If output formatting is on, we turn it off to ensure that the sorting
|
|
* is performed without output formatting.
|
|
*
|
|
* @param Wire $item
|
|
* @param string $property
|
|
* @return mixed
|
|
*
|
|
*/
|
|
protected function getItemPropertyValue(Wire $item, $property) {
|
|
|
|
if($item instanceof Page) {
|
|
$value = $item->getUnformatted($property);
|
|
} else if(strpos($property, '.') !== false) {
|
|
$value = WireData::_getDot($property, $item);
|
|
} else if($item instanceof WireArray) {
|
|
/** @var PageArray $item */
|
|
$value = $item->getProperty($property);
|
|
if(is_null($value)) {
|
|
$value = $item->first();
|
|
if($value) $value = $this->getItemPropertyValue($value, $property);
|
|
}
|
|
} else {
|
|
$value = $item->$property;
|
|
}
|
|
|
|
if(is_array($value)) $value = implode('|', $value);
|
|
|
|
return $value;
|
|
}
|
|
|
|
/**
|
|
* Allows iteration of the PageArray.
|
|
*
|
|
* #pw-internal
|
|
*
|
|
* @return Page[]|\ArrayObject|PageArrayIterator
|
|
*
|
|
*/
|
|
#[\ReturnTypeWillChange]
|
|
public function getIterator() {
|
|
if($this->lazyLoad) return new PageArrayIterator($this->data, $this->finderOptions);
|
|
return parent::getIterator();
|
|
}
|
|
|
|
/**
|
|
* PageArrays always return a string of the Page IDs separated by pipe "|" characters
|
|
*
|
|
* Pipe charactesr are used for compatibility with Selector OR statements
|
|
*
|
|
*/
|
|
public function __toString() {
|
|
$s = '';
|
|
foreach($this as $key => $page) $s .= "$page|";
|
|
$s = rtrim($s, "|");
|
|
return $s;
|
|
}
|
|
|
|
/**
|
|
* Render a simple/default markup value for each item in this PageArray.
|
|
*
|
|
* For testing/debugging purposes.
|
|
*
|
|
* #pw-internal
|
|
*
|
|
* @param string|callable $key
|
|
* @return string
|
|
*
|
|
*/
|
|
public function ___getMarkup($key = null) {
|
|
if($key && !is_string($key)) {
|
|
$out = $this->each($key);
|
|
} else if(strpos($key, '{') !== false && strpos($key, '}')) {
|
|
$out = $this->each($key);
|
|
} else {
|
|
if(empty($key)) $key = "<li>{title|name}</li>";
|
|
$out = $this->each($key);
|
|
if($out) {
|
|
$out = "<ul>$out</ul>";
|
|
if($this->getLimit() && $this->getTotal() > $this->getLimit()) {
|
|
$pager = $this->wire('modules')->get('MarkupPagerNav');
|
|
$out .= $pager->render($this);
|
|
}
|
|
}
|
|
}
|
|
return $out;
|
|
}
|
|
|
|
|
|
/**
|
|
* debugInfo PHP 5.6+ magic method
|
|
*
|
|
* @return array
|
|
*
|
|
*/
|
|
public function __debugInfo() {
|
|
$info = parent::__debugInfo();
|
|
$info['selectors'] = (string) $this->selectors;
|
|
if(!wireCount($info['selectors'])) unset($info['selectors']);
|
|
return $info;
|
|
}
|
|
|
|
/**
|
|
* Get or set $options array used by $pages->find() for this PageArray
|
|
*
|
|
* #pw-internal
|
|
*
|
|
* @param array|null $options Specify array to set or omit this argument to get
|
|
* @return array
|
|
*
|
|
*/
|
|
public function finderOptions($options = null) {
|
|
if(is_array($options)) $this->finderOptions = $options;
|
|
return $this->finderOptions;
|
|
}
|
|
|
|
/**
|
|
* Get or set Lazy loading state of this PageArray
|
|
*
|
|
* #pw-internal
|
|
*
|
|
* @param bool|null $lazy
|
|
* @return bool
|
|
*
|
|
*/
|
|
public function _lazy($lazy = null) {
|
|
if(is_bool($lazy)) $this->lazyLoad = $lazy;
|
|
return $this->lazyLoad;
|
|
}
|
|
|
|
/**
|
|
* Track an item added
|
|
*
|
|
* @param Wire|mixed $item
|
|
* @param int|string $key
|
|
*
|
|
*/
|
|
protected function trackAdd($item, $key) {
|
|
parent::trackAdd($item, $key);
|
|
if(!$item instanceof Page) return;
|
|
/** @var Page $item */
|
|
if(!isset($this->keyIndex[$item->id])) $this->numTotal++;
|
|
$this->keyIndex[$item->id] = $key;
|
|
}
|
|
|
|
/**
|
|
* Track an item removed
|
|
*
|
|
* @param Wire|mixed $item
|
|
* @param int|string $key
|
|
*
|
|
*/
|
|
protected function trackRemove($item, $key) {
|
|
parent::trackRemove($item, $key);
|
|
if(!$item instanceof Page) return;
|
|
/** @var Page $item */
|
|
if(isset($this->keyIndex[$item->id])) {
|
|
if($this->numTotal) $this->numTotal--;
|
|
unset($this->keyIndex[$item->id]);
|
|
}
|
|
}
|
|
}
|
|
|
|
|