From f5096b5e2d3d2d8ead383138acf122681a07afe8 Mon Sep 17 00:00:00 2001
From: Greg Bowler <greg.bowler@g105b.com>
Date: Thu, 13 Feb 2025 14:46:52 +0000
Subject: [PATCH] Deprecate `with` functions (#305)

* ci: remove old artifacts

* ci: run all php versions

* deprecate: all with functions on the Input class
for #301

* deprecate: all with functions on the Trigger class
for #301

* tweak: deprecate pre-8.4 attribute

* tweak: until deprecations are removed, suppress TooManyPublicMethods

* tweak: line length
---
 src/Input.php           | 20 +++++++++++++++++---
 src/Trigger/Trigger.php | 38 +++++++++++++++++++++++++-------------
 2 files changed, 42 insertions(+), 16 deletions(-)

diff --git a/src/Input.php b/src/Input.php
index f6fe5c1..3ed042c 100644
--- a/src/Input.php
+++ b/src/Input.php
@@ -23,6 +23,7 @@
  * @implements ArrayAccess<string, ?string>
  * @implements Iterator<string, ?string>
  * @SuppressWarnings(PHPMD.CouplingBetweenObjects)
+ * @SuppressWarnings(PHPMD.TooManyPublicMethods)
  */
 class Input implements ArrayAccess, Countable, Iterator {
 	use InputValueGetter;
@@ -235,7 +236,7 @@ public function when(array|string...$matches):Trigger {
 	/**
 	 * Return a Trigger that will only pass the provided keys to its callback.
 	 */
-	public function with(string...$keys):Trigger {
+	public function select(string...$keys):Trigger {
 		foreach($keys as $key) {
 			if(!$this->parameters->contains($key)) {
 				throw new MissingInputParameterException($key);
@@ -245,20 +246,33 @@ public function with(string...$keys):Trigger {
 		return $this->newTrigger("with", ...$keys);
 	}
 
+	/** @deprecated Use select() instead to avoid ambiguity with immutable `with` functions */
+	public function with(string...$keys):Trigger {
+		return $this->select(...$keys);
+	}
+
 	/**
 	 * Return a Trigger that will pass all keys apart from the provided
 	 * keys to its callback.
 	 */
-	public function without(string...$keys):Trigger {
+	public function selectAllExcept(string...$keys):Trigger {
 		return $this->newTrigger("without", ...$keys);
 	}
+	/** @deprecated Use selectAllExcept() instead to avoid ambiguity with immutable `with` functions */
+	public function without(string...$keys):Trigger {
+		return $this->selectAllExcept(...$keys);
+	}
 
 	/**
 	 * Return a Trigger that will pass all keys to its callback.
 	 */
-	public function withAll():Trigger {
+	public function selectAll():Trigger {
 		return $this->newTrigger("withAll");
 	}
+	/** @deprecated Use selectAll() instead to avoid ambiguity with immutable `with` functions */
+	public function withAll():Trigger {
+		return $this->selectAll();
+	}
 
 	protected function newTrigger(string $functionName, string...$args):Trigger {
 		$trigger = new Trigger($this);
diff --git a/src/Trigger/Trigger.php b/src/Trigger/Trigger.php
index 82e1212..f029730 100644
--- a/src/Trigger/Trigger.php
+++ b/src/Trigger/Trigger.php
@@ -13,9 +13,9 @@ class Trigger {
 	/** @var array<string> */
 	protected array $keyMatches;
 	/** @var array<string> */
-	protected array $with;
+	protected array $select;
 	/** @var array<string> */
-	protected array $without;
+	protected array $selectAllExcept;
 	/** @var array<Callback> */
 	protected array $callbacks;
 	protected ?bool $hasFired;
@@ -27,8 +27,8 @@ public function __construct(Input $input) {
 
 		$this->matches = [];
 		$this->keyMatches = [];
-		$this->with = [];
-		$this->without = [];
+		$this->select = [];
+		$this->selectAllExcept = [];
 		$this->callbacks = [];
 		$this->hasFired = null;
 	}
@@ -49,28 +49,40 @@ public function when(string|array...$matches):self {
 		return $this;
 	}
 
-	public function with(string...$keys):self {
+	public function select(string...$keys):self {
 		foreach($keys as $key) {
-			$this->with []= $key;
+			$this->select []= $key;
 		}
 
 		return $this;
 	}
+	/** @deprecated Use select() instead to avoid ambiguity with immutable `with` functions */
+	public function with(string...$keys):self {
+		return $this->select(...$keys);
+	}
 
-	public function without(string...$keys):self {
+	public function selectAllExcept(string...$keys):self {
 		foreach($keys as $key) {
-			$this->without []= $key;
+			$this->selectAllExcept []= $key;
 		}
 
 		return $this;
 	}
+	/** @deprecated Use selectAllExcept() instead to avoid ambiguity with immutable `with` functions */
+	public function without(string...$keys):self {
+		return $this->selectAllExcept(...$keys);
+	}
 
-	public function withAll():self {
-		$this->with = [];
-		$this->without = [];
+	public function selectAll():self {
+		$this->select = [];
+		$this->selectAllExcept = [];
 
 		return $this;
 	}
+	/** @deprecated Use selectAll() instead to avoid ambiguity with immutable `with` functions */
+	public function withAll():self {
+		return $this->selectAll();
+	}
 
 	public function setTrigger(string $key, string $value):self {
 		if(!isset($this->matches[$key])) {
@@ -142,8 +154,8 @@ public function fire():bool {
 	protected function callCallbacks():void {
 		$fields = $this->inputDataFactory->create(
 			$this->input,
-			$this->with,
-			$this->without
+			$this->select,
+			$this->selectAllExcept
 		);
 
 		foreach($this->callbacks as $callback) {