Feat: 2.0 (#13)

Author: bpolaszek

.github/workflows/ci-workflow.yml

@@ -37,9 +37,6 @@ jobs:
       max-parallel: 10
       matrix:
         php:
-          - 7.4
-          - 8.0
-          - 8.1
           - 8.2
           - 8.3
           - 8.4
@@ -60,7 +57,7 @@ jobs:
         run: composer install --prefer-dist --no-progress --ignore-platform-req=php
 
       - name: Run tests
-        run: vendor/bin/phpunit --coverage-clover=coverage.xml
+        run: vendor/bin/pest --coverage-clover=coverage.xml
 
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v5

README.md

@@ -12,8 +12,6 @@ Usage
 -------
 
 ```php
-require_once __DIR__ . '/vendor/autoload.php';
-
 use function BenTools\CartesianProduct\combinations;
 
 $data = [
@@ -103,15 +101,12 @@ Array
 )
 ```
 
-
 Combinations count
 ------------------
 
-You can simply count how many combinations your data produce:
+You can simply count how many combinations your data produce (this will not generate any combination):
 
 ```php
-require_once __DIR__ . '/vendor/autoload.php';
-
 use function BenTools\CartesianProduct\combinations;
 
 $data = [
@@ -132,11 +127,54 @@ $data = [
 var_dump(count(combinations($data))); // 2 * 3 * 2 = 12
 ```
 
+Filtering combinations
+----------------------
+
+You can filter combinations using the `filter` method. This is useful if you want to skip some combinations based on certain criteria:
+
+```php
+use function BenTools\CartesianProduct\combinations;
+
+$data = [
+    'hair' => [
+        'blond',
+        'black'
+    ],
+    'eyes' => [
+        'blue',
+        'green',
+    ]
+];
+
+foreach (combinations($data)->filter(fn (array $combination) => 'green' !== $combination['eyes']) as $combination) {
+    printf('Hair: %s - Eyes: %s' . PHP_EOL, $combination['hair'], $combination['eyes']);
+}
+```
+
+Map output
+----------
+
+You can use the `each` method to transform each combination into a different format:
+
+```php
+use App\Entity\Book;
+
+use function BenTools\CartesianProduct\combinations;
+
+$books = [
+    'author' => ['Isaac Asimov', 'Arthur C. Clarke'],
+    'genre' => ['Science Fiction', 'Fantasy'],
+]
+
+foreach (combinations($books)->each(fn (array $combination) => Book::fromArray($combination)) as $book) {
+    assert($book instanceof Book);
+}
+```
 
 Installation
 ------------
 
-PHP 7.4+ is required.
+PHP 8.2+ is required.
 ```
 composer require bentools/cartesian-product
 ```
@@ -146,7 +184,6 @@ Performance test
 The following example was executed on my Core i7 personnal computer with 8GB RAM.
 
 ```php
-require_once __DIR__ . '/vendor/autoload.php';
 use function BenTools\CartesianProduct\combinations;
 
 $data = array_fill(0, 10, array_fill(0, 5, 'foo'));
@@ -172,7 +209,7 @@ Output:
 Unit tests
 ----------
 ```
-./vendor/bin/phpunit
+./vendor/bin/pest
 ```
 
 

composer.json

@@ -18,11 +18,17 @@
         ]
     },
     "require": {
-        "php": ">=7.4"
+        "php": "^8.2"
     },
     "require-dev": {
         "symfony/var-dumper": "^6.0|^7.0",
-        "phpunit/phpunit": "^9.0",
-        "friendsofphp/php-cs-fixer": "^3.82"
+        "friendsofphp/php-cs-fixer": "^3.82",
+        "pestphp/pest": "^3.8",
+        "pestphp/pest-plugin-drift": "^3.0"
+    },
+    "config": {
+        "allow-plugins": {
+            "pestphp/pest-plugin": true
+        }
     }
 }

phpunit.xml.dist

@@ -1,21 +1,17 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" backupGlobals="false" backupStaticAttributes="false"
-         beStrictAboutTestsThatDoNotTestAnything="true" beStrictAboutOutputDuringTests="true"
-         bootstrap="vendor/autoload.php" colors="true" convertErrorsToExceptions="true"
-         convertNoticesToExceptions="true" convertWarningsToExceptions="true" failOnRisky="true" failOnWarning="true"
-         processIsolation="false" stopOnError="false" stopOnFailure="false" verbose="true" convertDeprecationsToExceptions="false"
-         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd">
-    <coverage processUncoveredFiles="true">
-        <include>
-            <directory suffix=".php">./src</directory>
-        </include>
-    </coverage>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+         bootstrap="vendor/autoload.php"
+         colors="true"
+>
     <testsuites>
-        <testsuite name="New function">
-            <file>tests/TestCombinationsFunction.php</file>
-        </testsuite>
-        <testsuite name="Legacy function">
-            <file>tests/TestCartesianProductFunction.php</file>
+        <testsuite name="Test Suite">
+            <directory suffix="Test.php">./tests</directory>
         </testsuite>
     </testsuites>
+    <source>
+        <include>
+            <directory>src</directory>
+        </include>
+    </source>
 </phpunit>

src/CartesianProduct.php

@@ -18,7 +18,7 @@
 use function iterator_to_array;
 
 /**
- * @internal - use the function `cartesian_product()` instead.
+ * @internal - use the function `combinations()` instead.
  * @template TKey
  * @template TValue
  * @implements IteratorAggregate<array<TKey, TValue>>
@@ -31,6 +31,8 @@ final class CartesianProduct implements IteratorAggregate, Countable
     private array $set;
     private bool $isRecursiveStep = false;
     private int $count;
+    private ?Closure $filterCallback = null;
+    private ?Closure $mapCallback = null;
 
     /**
      * @param array<TKey, iterable<TValue>> $set
@@ -40,6 +42,22 @@ public function __construct(array $set)
         $this->set = $set;
     }
 
+    public function filter(callable $callback): self
+    {
+        $clone = clone $this;
+        $clone->filterCallback = Closure::fromCallable($callback);
+
+        return $clone;
+    }
+
+    public function each(callable $callback): self
+    {
+        $clone = clone $this;
+        $clone->mapCallback = Closure::fromCallable($callback);
+
+        return $clone;
+    }
+
     /**
      * @return Traversable<array<TKey, TValue>>
      */
@@ -60,7 +78,11 @@ public function getIterator(): Traversable
         $this->validate($subset, $last);
         foreach (self::subset($set) as $product) {
             foreach ($subset as $value) {
-                yield $product + [$last => ($value instanceof Closure ? $value($product) : $value)];
+                $combination = $product + [$last => ($value instanceof Closure ? $value($product) : $value)];
+                if ($this->filterCallback && !($this->filterCallback)($combination)) {
+                    continue;
+                }
+                yield $this->mapCallback ? ($this->mapCallback)($combination) : $combination;
             }
         }
     }
@@ -91,7 +113,7 @@ function ($subset, $key) {
      * @param mixed $subset
      * @param TKey $key
      */
-    private function validate($subset, $key): void
+    private function validate(mixed $subset, $key): void
     {
         // Validate array subset
         if (is_array($subset) && !empty($subset)) {

src/function.php

@@ -2,29 +2,6 @@
 
 namespace BenTools\CartesianProduct;
 
-use function trigger_error;
-
-use const E_USER_DEPRECATED;
-
-require_once __DIR__ . '/CartesianProduct.php';
-
-/**
- * @template TKey
- * @template TValue
- * @param  array<TKey, iterable<TValue>> $set - A multidimensionnal array.
- * @return CartesianProduct<TKey, TValue>
- */
-function cartesian_product(array $set): CartesianProduct
-{
-    trigger_error(sprintf(
-        'The function %s() is deprecated since 1.5 and will be removed in 2.0. Use %s() instead.',
-        __FUNCTION__,
-        'BenTools\CartesianProduct\combinations'
-    ), E_USER_DEPRECATED);
-
-    return new CartesianProduct($set);
-}
-
 /**
  * @template TKey
  * @template TValue