From 25a3477b67b91924443bc5f7c1a7341208ef85d5 Mon Sep 17 00:00:00 2001
From: Ryan Cramer <ryan@processwire.com>
Date: Wed, 28 Apr 2021 13:58:37 -0400
Subject: [PATCH] Add a field rename option to $pages->findRaw()

---
 wire/core/Pages.php    |  4 +++
 wire/core/PagesRaw.php | 56 ++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 58 insertions(+), 2 deletions(-)

diff --git a/wire/core/Pages.php b/wire/core/Pages.php
index 8f16ae16..d52d60a7 100644
--- a/wire/core/Pages.php
+++ b/wire/core/Pages.php
@@ -511,6 +511,10 @@ class Pages extends Wire {
 	 * // You can also use this format below to get multiple subfields from one field:
 	 * $a = $pages->findRaw("template=blog", [ "title", "categories" => [ "id", "title" ] ]); 
 	 * 
+	 * // You can optionally rename fields in the returned value like this below, which
+	 * // asks the 'title' field to have the name 'headline' in return value (3.0.176+):
+	 * $a = $pages->findRaw("template=blog", [ "title" => "headline" ]); 
+	 * 
 	 * // You may specify wildcard field name(s) like `field.*` to return all columns 
 	 * // for `field`. This retrieves all columns from the field’s table. This is 
 	 * // especially useful with fields like Table or Combo that might have several 
diff --git a/wire/core/PagesRaw.php b/wire/core/PagesRaw.php
index 16a6f946..3d493562 100644
--- a/wire/core/PagesRaw.php
+++ b/wire/core/PagesRaw.php
@@ -31,6 +31,7 @@ class PagesRaw extends Wire {
 	 *
 	 * @param string|array|Selectors $selector
 	 * @param string|Field|int|array $field Field/property name to get or array of them (or omit to get all)
+	 *  - Optionally use associative array to rename fields in returned value, i.e. `['title' => 'label']` returns 'title' as 'label' in return value.
 	 * @param array $options See options for Pages::find
 	 *  - `objects` (bool): Use objects rather than associative arrays? (default=false)
 	 *  - `entities` (bool|array): Entity encode string values? True, or specify array of field names. (default=false)
@@ -146,6 +147,14 @@ class PagesRawFinder extends Wire {
 	 */
 	protected $runtimeFields = array();
 
+	/**
+	 * Fields to rename in returned value, i.e. [ 'title' => 'label' ]
+	 * 
+	 * @var array
+	 * 
+	 */
+	protected $renameFields = array();
+
 	/**
 	 * @var array
 	 *
@@ -278,8 +287,19 @@ class PagesRawFinder extends Wire {
 			$this->requestFields = explode(',', $field);
 			
 		} else if(is_array($field)) {
-			// one or more fields requested in array, we wil return an array for each page
-			$this->requestFields = $field;
+			// one or more fields requested in array, we will return an array for each page
+			$requestFields = array();
+			$renameFields = array();
+			foreach($field as $key => $value) {
+				if(is_string($key) && !ctype_digit($key) && !is_array($value)) {
+					$requestFields[] = $key;
+					$renameFields[$key] = $value;
+				} else {
+					$requestFields[] = $value;
+				}
+			}
+			$this->requestFields = $requestFields;
+			$this->renameFields = $renameFields;
 			
 		} else {
 			// one field requested in string or Field object
@@ -345,6 +365,11 @@ class PagesRawFinder extends Wire {
 	 *
 	 * - You may request field name(s) like `field.*` to return all columns/subfields for `field`,
 	 *   in this case, an associative array value will be returned for each page.
+	 * 
+	 * - If you specify an associative array for the $field argument, you can optionally rename 
+	 *   fields in returned value. For example, if you wanted to get the 'title' field but return 
+	 *   it as a field named 'headline' in the return value, you would specify the array 
+	 *   `[ 'title' => 'headline' ]` for the $field argument. (3.0.176+)
 	 *
 	 * @param string|array|Selectors $selector
 	 * @param string|Field|int|array $field Field/property name or array of of them
@@ -382,6 +407,10 @@ class PagesRawFinder extends Wire {
 			$this->values = array_values($this->values);
 		}
 		
+		if(count($this->renameFields)) {
+			$this->renames($this->values);
+		}	
+		
 		if($this->options['entities']) {
 			if($this->options['objects'] || $level === 1) {
 				$this->entities($this->values);
@@ -954,6 +983,29 @@ class PagesRawFinder extends Wire {
 		}
 	}
 
+	/**
+	 * Rename fields on request
+	 * 
+	 * @param array $values
+	 * @since 3.0.167
+	 * 
+	 */
+	protected function renames(&$values) {
+		foreach($values as $key => $value) {
+			if(!is_array($value)) continue;
+			foreach($value as $k => $v) {
+				if(is_array($v)) $this->renames($v);
+				if(isset($this->renameFields[$k])) {
+					unset($values[$key][$k]);
+					$name = $this->renameFields[$k];
+				} else {
+					$name = $k;
+				}
+				$values[$key][$name] = $v;
+			}
+		}
+	}
+
 	/**
 	 * Get or convert $this->ids to/from CSV
 	 *