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

Author: Greg Bowler

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);

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) {