refactor(support): clarify has and contains methods (#1296)

Author: innocenzi

packages/console/src/Middleware/ResolveOrRescueMiddleware.php

@@ -84,7 +84,7 @@ private function getSimilarCommands(ImmutableString $search): ImmutableArray
             $currentName = str($consoleCommand->getName());
 
             // Already added to suggestions
-            if ($suggestions->contains($currentName->toString())) {
+            if ($suggestions->hasValue($currentName->toString())) {
                 continue;
             }
 

packages/console/src/Middleware/ValidateNamedArgumentsMiddleware.php

@@ -29,7 +29,7 @@ public function __invoke(Invocation $invocation, ConsoleMiddlewareCallable $next
 
         $invalidInput = arr($invocation->argumentBag->arguments)
             ->filter(fn (ConsoleInputArgument $argument) => $argument->name !== null)
-            ->filter(fn (ConsoleInputArgument $argument) => ! $allowedParameterNames->contains(ltrim($argument->name, '-')))
+            ->filter(fn (ConsoleInputArgument $argument) => ! $allowedParameterNames->hasValue(ltrim($argument->name, '-')))
             ->filter(fn (ConsoleInputArgument $argument) => ! in_array($argument->name, GlobalFlags::values(), strict: true));
 
         if ($invalidInput->isNotEmpty()) {

packages/database/src/Mappers/SelectModelMapper.php

@@ -103,7 +103,7 @@ public function normalizeRow(ModelInspector $model, array $row, MutableArray $da
 
                     $originalKey .= $relation->name . '.';
 
-                    if (! $data->has(trim($originalKey, '.'))) {
+                    if (! $data->hasKey(trim($originalKey, '.'))) {
                         $data->set(trim($originalKey, '.'), []);
                     }
 

packages/http/src/IsRequest.php

@@ -11,7 +11,7 @@
 
 use function Tempest\get;
 use function Tempest\Support\Arr\get_by_key;
-use function Tempest\Support\Arr\has;
+use function Tempest\Support\Arr\has_key;
 
 /** @phpstan-require-implements \Tempest\Http\Request */
 trait IsRequest
@@ -125,14 +125,14 @@ public function has(string $key): bool
     public function hasBody(?string $key = null): bool
     {
         if ($key) {
-            return has($this->body, $key);
+            return has_key($this->body, $key);
         }
 
         return count($this->body) || ((bool) $this->raw);
     }
 
     public function hasQuery(string $key): bool
     {
-        return has($this->query, $key);
+        return has_key($this->query, $key);
     }
 }

packages/http/src/Mappers/PsrRequestToGenericRequestMapper.php

@@ -28,7 +28,7 @@ public function map(mixed $from, mixed $to): GenericRequest
         $data = (array) $from->getParsedBody();
         $raw = $from->getBody()->getContents();
 
-        if (arr($from->getHeader('content-type'))->contains('application/json') && json_validate($raw)) {
+        if (arr($from->getHeader('content-type'))->hasValue('application/json') && json_validate($raw)) {
             $data = [...$data, ...json_decode($raw, associative: true)];
         }
 

packages/support/src/Arr/ManipulatesArray.php

@@ -517,7 +517,7 @@ public function mapWithKeys(Closure $map): self
      */
     public function get(int|string $key, mixed $default = null): mixed
     {
-        return get_by_key($this->value, $key, $default);
+        return namespace\get_by_key($this->value, $key, $default);
     }
 
     /**
@@ -537,21 +537,45 @@ public function put(string $key, mixed $value): self
     }
 
     /**
-     * Asserts whether a value identified by the specified `$key` exists.
+     * Asserts whether the instance has the given item. A callback may be used instead of a value.
+     *
+     * @see `hasValue`
+     * @param TValue|Closure(TValue, TKey): bool $search
      */
-    public function has(int|string $key): bool
+    public function contains(mixed $search): bool
     {
-        return namespace\has($this->value, $key);
+        return namespace\contains($this->value, $search);
     }
 
     /**
-     * Asserts whether the instance contains an item that can be identified by `$search`.
+     * Asserts whether a value identified by the specified `$key` exists. Dot notation is supported.
      */
-    public function contains(mixed $search): bool
+    public function hasKey(int|string $key): bool
+    {
+        return namespace\has_key($this->value, $key);
+    }
+
+    /**
+     * Asserts whether the instance contains the specified value.
+     *
+     * @param TValue: bool $search
+     */
+    public function hasValue(mixed $search): bool
     {
         return namespace\contains($this->value, $search);
     }
 
+    /**
+     * Asserts whether the instance contains the specified value.
+     *
+     * @see `hasValue`
+     * @param TValue|Closure(TValue, TKey): bool $search
+     */
+    public function includes(mixed $search): bool
+    {
+        return $this->hasValue($search);
+    }
+
     /**
      * Asserts whether all items in the instance pass the given `$callback`.
      *

packages/support/src/Arr/functions.php

@@ -807,9 +807,9 @@ function get_by_key(iterable $array, int|string $key, mixed $default = null): mi
     }
 
     /**
-     * Asserts whether a value identified by the specified `$key` exists.
+     * Asserts whether a value identified by the specified `$key` exists. Dot notation is supported.
      */
-    function has(iterable $array, int|string $key): bool
+    function has_key(iterable $array, int|string $key): bool
     {
         $array = to_array($array);
 
@@ -833,11 +833,21 @@ function has(iterable $array, int|string $key): bool
     }
 
     /**
-     * Asserts whether the given array contains an item that can be identified by `$search`.
+     * Asserts whether the given array contains a value that can be identified by `$search`.
+     *
+     * @template TKey of array-key
+     * @template TValue
+     *
+     * @param iterable<TKey,TValue> $array
+     * @param TValue|Closure(TValue, TKey): bool $search
      */
     function contains(iterable $array, mixed $search): bool
     {
-        return namespace\first(to_array($array), fn (mixed $value) => $value === $search) !== null;
+        $search = ($search instanceof Closure)
+            ? $search
+            : static fn (mixed $value) => $value === $search;
+
+        return namespace\first(to_array($array), $search) !== null;
     }
 
     /**

packages/support/tests/Arr/ManipulatesArrayTest.php

@@ -92,17 +92,17 @@ public function test_get(): void
         $this->assertSame('b', arr($array)->get('a'));
     }
 
-    public function test_arr_has(): void
+    public function test_arr_has_key(): void
     {
         $array = [
             'a' => [
                 'b' => 'c',
             ],
         ];
 
-        $this->assertTrue(arr($array)->has('a.b'));
-        $this->assertTrue(arr($array)->has('a'));
-        $this->assertFalse(arr($array)->has('a.x'));
+        $this->assertTrue(arr($array)->hasKey('a.b'));
+        $this->assertTrue(arr($array)->hasKey('a'));
+        $this->assertFalse(arr($array)->hasKey('a.x'));
     }
 
     public function test_arr_set(): void
@@ -330,6 +330,21 @@ public function test_contains(): void
     {
         $this->assertTrue(arr(['a', 'b', 'c'])->contains('b'));
         $this->assertFalse(arr(['a', 'b', 'c'])->contains('d'));
+
+        $this->assertTrue(arr(['a', 'b', 'c'])->includes('b'));
+        $this->assertFalse(arr(['a', 'b', 'c'])->includes('d'));
+
+        $this->assertTrue(arr(['a', 'b', 'c'])->hasValue('b'));
+        $this->assertFalse(arr(['a', 'b', 'c'])->hasValue('d'));
+
+        $this->assertTrue(arr(['a', 'b', 'c'])->contains(fn (string $v) => $v === 'b'));
+        $this->assertFalse(arr(['a', 'b', 'c'])->contains(fn (string $v) => $v === 'd'));
+
+        $this->assertTrue(arr(['a', 'b', 'c'])->hasValue(fn (string $v) => $v === 'b'));
+        $this->assertFalse(arr(['a', 'b', 'c'])->hasValue(fn (string $v) => $v === 'd'));
+
+        $this->assertTrue(arr(['a', 'b', 'c'])->includes(fn (string $v) => $v === 'b'));
+        $this->assertFalse(arr(['a', 'b', 'c'])->includes(fn (string $v) => $v === 'd'));
     }
 
     public function test_explode(): void

packages/validation/src/Validator.php

@@ -63,7 +63,7 @@ public function validateValuesForClass(ClassReflector|string $class, ?array $val
 
             $key = $prefix . $property->getName();
 
-            if (! $values->has($key) && $property->hasDefaultValue()) {
+            if (! $values->hasKey($key) && $property->hasDefaultValue()) {
                 continue;
             }
 

src/Tempest/Framework/Testing/InstallerTester.php

@@ -121,7 +121,7 @@ public function assertFileNotContains(string $path, string $search): self
     public function assertCommandExecuted(string $command): self
     {
         Assert::assertTrue(
-            condition: arr($this->executor->executedCommands)->contains($command),
+            condition: arr($this->executor->executedCommands)->hasValue($command),
             message: sprintf('The command `%s` was not executed', $command),
         );