From 74ac0ceb7ad7118340c32113811c6e925ad79a48 Mon Sep 17 00:00:00 2001
From: Ryan Cramer <ryan@processwire.com>
Date: Fri, 10 Jul 2020 12:56:08 -0400
Subject: [PATCH] Addtion of some Page-specific convenience methods added to
 PageArray class

---
 wire/core/PageArray.php | 88 ++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 87 insertions(+), 1 deletion(-)

diff --git a/wire/core/PageArray.php b/wire/core/PageArray.php
index 5fdee16d..ecdddb59 100644
--- a/wire/core/PageArray.php
+++ b/wire/core/PageArray.php
@@ -518,6 +518,23 @@ class PageArray extends PaginatedArray implements WirePaginatable {
 		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)
 	 *
@@ -527,6 +544,7 @@ class PageArray extends PaginatedArray implements WirePaginatable {
 	 *
 	 * @param string $selector AttributeSelector string.
 	 * @return PageArray|WireArray New PageArray instance
+	 * @see WireArray::find()
 	 *
 	 */
 	public function find($selector) {
@@ -534,18 +552,86 @@ class PageArray extends PaginatedArray implements WirePaginatable {
 	}
 
 	/**
-	 * Same as find, but returns a single Page rather than PageArray or FALSE if empty.
+	 * 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
 	 *