From cc34ec8752bbeef897cd86fb55204a3597c40bed Mon Sep 17 00:00:00 2001
From: Ryan Cramer <ryan@rc-d.net>
Date: Fri, 8 Sep 2017 10:07:25 -0400
Subject: [PATCH] Add support to Pages/PagesLoader for populating directly to
 existing PageArray

---
 wire/core/Pages.php            | 9 ++++++++-
 wire/core/PagesLoader.php      | 2 ++
 wire/core/PagesLoaderCache.php | 2 +-
 3 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/wire/core/Pages.php b/wire/core/Pages.php
index 35ae7fc4..5a75f141 100644
--- a/wire/core/Pages.php
+++ b/wire/core/Pages.php
@@ -645,6 +645,7 @@ class Pages extends Wire {
 	 * - `findTemplates` (boolean): Determine which templates will be used (when no template specified) for more specific autojoins. (default=true)
 	 * - `pageClass` (string): Class to instantiate Page objects with. Leave blank to determine from template. (default=auto-detect)
 	 * - `pageArrayClass` (string): PageArray-derived class to store pages in (when 'getOne' is false). (default=PageArray)
+	 * - `pageArray` (PageArray|null): Populate this existing PageArray rather than creating a new one. (default=null)
 	 * - `page` (Page|null): Existing Page object to populate (also requires the getOne option to be true). (default=null)
 	 * 
 	 * **Use the `$options` array for potential speed optimizations:**
@@ -1196,11 +1197,17 @@ class Pages extends Wire {
 	 * 
 	 * #pw-internal
 	 * 
-	 * @param array $options Optionally specify array('pageArrayClass' => 'YourPageArrayClass')
+	 * @param array $options Optionally specify ONE of the following: 
+	 *  - `pageArrayClass` (string): Name of PageArray class to use (if not “PageArray”).
+	 *  - `pageArray` (PageArray): Wire and return this given PageArray, rather than instantiating a new one. 
 	 * @return PageArray
 	 * 
 	 */
 	public function newPageArray(array $options = array()) {
+		if(!empty($options['pageArray']) && $options['pageArray'] instanceof PageArray) {
+			$this->wire($options['pageArray']);
+			return $options['pageArray'];
+		}
 		$class = 'PageArray';
 		if(!empty($options['pageArrayClass'])) $class = $options['pageArrayClass'];
 		$class = wireClassName($class, true);
diff --git a/wire/core/PagesLoader.php b/wire/core/PagesLoader.php
index a9e7b539..d83a6884 100644
--- a/wire/core/PagesLoader.php
+++ b/wire/core/PagesLoader.php
@@ -446,6 +446,7 @@ class PagesLoader extends Wire {
 	 * - findTemplates: boolean, default=true. Determine which templates will be used (when no template specified) for more specific autojoins.
 	 * - pageClass: string, default=auto-detect. Class to instantiate Page objects with. Leave blank to determine from template.
 	 * - pageArrayClass: string, default=PageArray. PageArray-derived class to store pages in (when 'getOne' is false).
+	 * - pageArray: PageArray, default=null. Optional predefined PageArray to populate to. 
 	 * - page (Page|null): Existing Page object to populate (also requires the getOne option to be true). (default=null)
 	 * - caller (string): Name of calling function, for debugging purposes (default=blank).
 	 *
@@ -483,6 +484,7 @@ class PagesLoader extends Wire {
 			'joinFields' => array(),
 			'page' => null, 
 			'pageClass' => '',  // blank = auto detect
+			'pageArray' => null, // PageArray to populate to
 			'pageArrayClass' => 'PageArray',
 			'caller' => '', 
 		);
diff --git a/wire/core/PagesLoaderCache.php b/wire/core/PagesLoaderCache.php
index f5be63ea..b1449bf7 100644
--- a/wire/core/PagesLoaderCache.php
+++ b/wire/core/PagesLoaderCache.php
@@ -189,7 +189,7 @@ class PagesLoaderCache extends Wire {
 	 * @param string $selector
 	 * @param array $options
 	 * @param bool $returnSelector default false
-	 * @return array|null|string
+	 * @return array|null|string|PageArray
 	 *
 	 */
 	public function getSelectorCache($selector, $options, $returnSelector = false) {