From 119ee9ab8c2db6c2f3119fff46f122dc176767d2 Mon Sep 17 00:00:00 2001
From: Ryan Cramer <ryan@processwire.com>
Date: Fri, 23 Jul 2021 09:51:42 -0400
Subject: [PATCH] Add support to accept array value for
 Fieldtype::getMatchQuery(), plus documentation improvements to that method

---
 wire/core/Fieldtype.php | 40 +++++++++++++++++++++++++++++++++-------
 1 file changed, 33 insertions(+), 7 deletions(-)

diff --git a/wire/core/Fieldtype.php b/wire/core/Fieldtype.php
index f2f35366..ae3412d3 100644
--- a/wire/core/Fieldtype.php
+++ b/wire/core/Fieldtype.php
@@ -700,30 +700,56 @@ abstract class Fieldtype extends WireData implements Module {
 	/**
 	 * Get the database query that matches a Fieldtype table’s data with a given value.
 	 *
-	 * Possible template method: If overridden, children should not call this parent method. 
+	 * Possible template method: If overridden, children do not need to call this method
+	 * if they update the $query themselves. 
+	 *
+	 * Note the following additional properties are available from the $query argument: 
+	 * 
+	 *  - `$query->field` (Field): Field instance that being referred to match.
+	 *  - `$query->group` (string): Original group of the field in the selector (when applicable).
+	 *  - `$query->selector` (Selector): Original Selector object (matching the $field).
+	 *  - `$query->selectors` (Selectors): Original Selectors object (matching $field and others).
+	 *  - `$query->parentQuery` (DatabaseQuerySelect): Parent database query that $query will be merged into.
+	 *  - `$query->pageFinder` (PageFinder): The PageFinder instance that initiated the query, for additional info.
 	 * 
 	 * #pw-group-finding
 	 *
 	 * @param PageFinderDatabaseQuerySelect $query
 	 * @param string $table The table name to use
 	 * @param string $subfield Name of the subfield (typically 'data', unless selector explicitly specified another)
-	 * @param string $operator The comparison operator
-	 * @param mixed $value The value to find
+	 * @param string $operator The comparison operator. 
+	 *  - This base Fieldtype class accepts only database operators (=, !=, >, >=, <, <=, &). 
+	 *  - Other Fieldtypes may choose to accept more operators according to need of Fieldtype.
+	 * @param mixed $value Value to find. 
+	 *  - If given array, this base Fieldtype class (only) will match via OR condition. (3.0.182+)
+	 *  - Other Fieldtypes may choose to interpret array values differently according need of Fieldtype.
 	 * @return PageFinderDatabaseQuerySelect|DatabaseQuerySelect $query
 	 * @throws WireException
 	 *
 	 */
 	public function getMatchQuery($query, $table, $subfield, $operator, $value) {
 
-		$database = $this->wire('database');
+		$database = $this->wire()->database;
 
-		if(!$database->isOperator($operator)) 
-			throw new WireException("Operator '{$operator}' is not implemented in {$this->className}"); 
+		if(!$database->isOperator($operator)) {
+			throw new WireException("Operator '{$operator}' is not implemented in {$this->className}");
+		}
 
 		$table = $database->escapeTable($table); 
 		$subfield = $database->escapeCol($subfield);
 		$operator = $database->escapeOperator($operator, WireDatabasePDO::operatorTypeComparison); 
-		$query->where("{$table}.{$subfield}{$operator}?", $value); // QA
+		
+		if(is_array($value)) {
+			$a = array();
+			foreach($value as $v) {
+				$bindKey = $query->bindValueGetKey($v);
+				$a[] = "{$table}.{$subfield}{$operator}{$bindKey}";
+			}
+			$query->where('(' . implode(' OR ', $a) . ')'); 
+		} else {
+			$query->where("{$table}.{$subfield}{$operator}?", $value); // QA
+		}
+		
 		return $query; 
 	}