Introduce ContainsCount validator

This validator is similar to Contains, but also checks how many
times the needle appears.

Additionally, the Domain validator was changed to use it instead
of relying on an unserializable callback, thus, making it
serializable.

Author: alganet

docs/validators/Contains.md

@@ -56,6 +56,7 @@ Message template for this validator includes `{{containsValue}}`.
 See also:
 
 - [ContainsAny](ContainsAny.md)
+- [ContainsCount](ContainsCount.md)
 - [EndsWith](EndsWith.md)
 - [Equals](Equals.md)
 - [Equivalent](Equivalent.md)

docs/validators/ContainsAny.md

@@ -57,5 +57,6 @@ See also:
 
 - [AnyOf](AnyOf.md)
 - [Contains](Contains.md)
+- [ContainsCount](ContainsCount.md)
 - [Equivalent](Equivalent.md)
 - [In](In.md)

docs/validators/ContainsCount.md

@@ -0,0 +1,73 @@
+# ContainsCount
+
+- `ContainsCount(mixed $containsValue, int $count)`
+- `ContainsCount(mixed $containsValue, int $count, bool $identical)`
+
+Validates if the input contains a value a specific number of times.
+
+For strings:
+
+```php
+v::containsCount('ipsum', 2)->assert('ipsum lorem ipsum');
+// Validation passes successfully
+```
+
+For arrays:
+
+```php
+v::containsCount('ipsum', 2)->assert(['ipsum', 'lorem', 'ipsum']);
+// Validation passes successfully
+```
+
+A third parameter may be passed for identical comparison instead of equal comparison.
+
+```php
+v::containsCount(1, 1, true)->assert([1, 2, 3]);
+// Validation passes successfully
+
+v::containsCount('1', 1, true)->assert([1, 2, 3]);
+// → `[1, 2, 3]` must contain "1" 1 times
+```
+
+## Templates
+
+### `ContainsCount::TEMPLATE_STANDARD`
+
+| Mode       | Template                                                       |
+| ---------- | -------------------------------------------------------------- |
+| `default`  | {{subject}} must contain {{containsValue}} {{count}} times     |
+| `inverted` | {{subject}} must not contain {{containsValue}} {{count}} times |
+
+## Template placeholders
+
+| Placeholder     | Description                                                      |
+| --------------- | ---------------------------------------------------------------- |
+| `containsValue` |                                                                  |
+| `subject`       | The validated input or the custom validator name (if specified). |
+| `count`         | Number of times that the needle might appear in the haystack.    |
+
+## Categorization
+
+- Arrays
+- Strings
+
+## Changelog
+
+| Version | Description |
+| ------: | ----------- |
+|   3.0.0 | Created     |
+
+---
+
+See also:
+
+- [Contains](Contains.md)
+- [ContainsAny](ContainsAny.md)
+- [EndsWith](EndsWith.md)
+- [Equals](Equals.md)
+- [Equivalent](Equivalent.md)
+- [Identical](Identical.md)
+- [In](In.md)
+- [Regex](Regex.md)
+- [StartsWith](StartsWith.md)
+- [Unique](Unique.md)

docs/validators/index.md

@@ -8,6 +8,7 @@ In this page you will find a list of validators by their category.
 - [ArrayVal](validators/ArrayVal.md)
 - [Contains](validators/Contains.md)
 - [ContainsAny](validators/ContainsAny.md)
+- [ContainsCount](validators/ContainsCount.md)
 - [Each](validators/Each.md)
 - [EndsWith](validators/EndsWith.md)
 - [In](validators/In.md)
@@ -228,6 +229,7 @@ In this page you will find a list of validators by their category.
 - [Consonant](validators/Consonant.md)
 - [Contains](validators/Contains.md)
 - [ContainsAny](validators/ContainsAny.md)
+- [ContainsCount](validators/ContainsCount.md)
 - [Control](validators/Control.md)
 - [Digit](validators/Digit.md)
 - [Emoji](validators/Emoji.md)
@@ -331,6 +333,7 @@ In this page you will find a list of validators by their category.
 - [Consonant](validators/Consonant.md)
 - [Contains](validators/Contains.md)
 - [ContainsAny](validators/ContainsAny.md)
+- [ContainsCount](validators/ContainsCount.md)
 - [Control](validators/Control.md)
 - [Countable](validators/Countable.md)
 - [CountryCode](validators/CountryCode.md)

library/Mixins/Builder.php

@@ -84,6 +84,8 @@ public static function contains(mixed $containsValue, bool $identical = false):
     /** @param non-empty-array<mixed> $needles */
     public static function containsAny(array $needles, bool $identical = false): Chain;
 
+    public static function containsCount(mixed $containsValue, int $count, bool $identical = false): Chain;
+
     public static function control(string ...$additionalChars): Chain;
 
     public static function countable(): Chain;

library/Mixins/Chain.php

@@ -87,6 +87,8 @@ public function contains(mixed $containsValue, bool $identical = false): Chain;
     /** @param non-empty-array<mixed> $needles */
     public function containsAny(array $needles, bool $identical = false): Chain;
 
+    public function containsCount(mixed $containsValue, int $count, bool $identical = false): Chain;
+
     public function control(string ...$additionalChars): Chain;
 
     public function countable(): Chain;

library/Validators/ContainsCount.php

@@ -0,0 +1,79 @@
+<?php
+
+/*
+ * Copyright (c) Alexandre Gomes Gaigalas <alganet@gmail.com>
+ * SPDX-License-Identifier: MIT
+ */
+
+declare(strict_types=1);
+
+namespace Respect\Validation\Validators;
+
+use Attribute;
+use Respect\Validation\Message\Template;
+use Respect\Validation\Result;
+use Respect\Validation\Validator;
+
+use function in_array;
+use function is_array;
+use function is_scalar;
+use function mb_strtolower;
+use function mb_substr_count;
+
+#[Attribute(Attribute::TARGET_PROPERTY | Attribute::IS_REPEATABLE)]
+#[Template(
+    '{{subject}} must contain {{containsValue}} {{count}} times',
+    '{{subject}} must not contain {{containsValue}} {{count}} times',
+)]
+final readonly class ContainsCount implements Validator
+{
+    public function __construct(
+        private mixed $containsValue,
+        private int $count,
+        private bool $identical = false,
+    ) {
+    }
+
+    public function evaluate(mixed $input): Result
+    {
+        return Result::of(
+            $this->countOccurrences($input) === $this->count,
+            $input,
+            $this,
+            ['containsValue' => $this->containsValue, 'count' => $this->count],
+        );
+    }
+
+    private function countOccurrences(mixed $input): int|null
+    {
+        if (is_array($input)) {
+            $count = 0;
+            foreach ($input as $item) {
+                if (!in_array($this->containsValue, [$item], $this->identical)) {
+                    continue;
+                }
+
+                $count++;
+            }
+
+            return $count;
+        }
+
+        if (!is_scalar($input) || !is_scalar($this->containsValue)) {
+            return null;
+        }
+
+        $haystack = (string) $input;
+        $needle = (string) $this->containsValue;
+
+        if ($needle === '') {
+            return null;
+        }
+
+        if ($this->identical) {
+            return mb_substr_count($haystack, $needle);
+        }
+
+        return mb_substr_count(mb_strtolower($haystack), mb_strtolower($needle));
+    }
+}

library/Validators/Domain.php

@@ -17,7 +17,6 @@
 use function array_pop;
 use function count;
 use function explode;
-use function mb_substr_count;
 
 #[Attribute(Attribute::TARGET_PROPERTY | Attribute::IS_REPEATABLE)]
 #[Template(
@@ -84,9 +83,7 @@ private function createPartsRule(): Validator
                 new Not(new StartsWith('-')),
                 new AnyOf(
                     new Not(new Contains('--')),
-                    new Callback(static function ($str) {
-                        return mb_substr_count($str, '--') == 1;
-                    }),
+                    new ContainsCount('--', 1),
                 ),
                 new Not(new EndsWith('-')),
             ),

tests/benchmark/ValidatorBench.php

@@ -46,6 +46,7 @@ public function provideValidatorInput(): Generator
         yield 'Consonant' => [v::consonant(), 'bcdf'];
         yield 'Contains' => [v::contains('needle'), 'haystack needle'];
         yield 'ContainsAny' => [v::containsAny(['a', 'b']), 'abc'];
+        yield 'ContainsCount' => [v::containsCount('a', 3), 'banana'];
         yield 'Control' => [v::control(), "\n\r"];
         yield 'Countable' => [v::countable(), []];
         yield 'CountryCode' => [v::countryCode(), 'US'];
@@ -55,6 +56,7 @@ public function provideValidatorInput(): Generator
         yield 'DateTime' => [v::dateTime(), '2020-01-01 12:00:00'];
         yield 'Decimal' => [v::decimal(2), '1.23'];
         yield 'Digit' => [v::digit(), '7'];
+        yield 'Domain' => [v::domain(), 'example.com'];
         yield 'Each' => [v::each(v::stringType()), ['a', 'b']];
         yield 'Email' => [v::email(), 'bob@example.com'];
         yield 'EndsWith' => [v::endsWith('.com'), 'example.com'];

tests/feature/Validators/ContainsCountTest.php

@@ -0,0 +1,28 @@
+<?php
+
+/*
+ * Copyright (c) Alexandre Gomes Gaigalas <alganet@gmail.com>
+ * SPDX-License-Identifier: MIT
+ */
+
+declare(strict_types=1);
+
+test('Scenario #1', catchMessage(
+    fn() => v::containsCount('foo', 2)->assert('bar'),
+    fn(string $message) => expect($message)->toBe('"bar" must contain "foo" 2 times'),
+));
+
+test('Scenario #2', catchMessage(
+    fn() => v::not(v::containsCount('foo', 2))->assert('foo bar foo'),
+    fn(string $message) => expect($message)->toBe('"foo bar foo" must not contain "foo" 2 times'),
+));
+
+test('Scenario #3', catchFullMessage(
+    fn() => v::containsCount('foo', 2)->assert(['foo']),
+    fn(string $fullMessage) => expect($fullMessage)->toBe('- `["foo"]` must contain "foo" 2 times'),
+));
+
+test('Scenario #4', catchFullMessage(
+    fn() => v::not(v::containsCount('foo', 1, true))->assert(['foo', 'bar']),
+    fn(string $fullMessage) => expect($fullMessage)->toBe('- `["foo", "bar"]` must not contain "foo" 1 times'),
+));