feat: Add select() as primary method, filter() becomes alias (#285)

Author: sanmai

.github/workflows/main.yml

@@ -52,7 +52,7 @@ jobs:
           composer remove --no-update --dev \
               phpstan/phpstan vimeo/psalm \
               infection/infection friendsofphp/php-cs-fixer php-coveralls/php-coveralls
-          composer update --prefer-dist --no-interaction --no-progress
+          composer install --prefer-dist --no-interaction --no-progress
 
       - name: Execute tests
         run: |
@@ -91,7 +91,7 @@ jobs:
           composer remove --no-update --dev \
               phpstan/phpstan vimeo/psalm \
               friendsofphp/php-cs-fixer
-          composer update --prefer-dist --no-interaction --no-progress
+          composer install --prefer-dist --no-interaction --no-progress
 
       - name: Generate coverage
         run: |
@@ -160,7 +160,7 @@ jobs:
       - name: Install dependencies
         run: |
           composer remove --no-update --dev infection/infection
-          composer update --prefer-dist --no-interaction --no-progress
+          composer install --prefer-dist --no-interaction --no-progress
 
       - name: Validate composer.json
         run: |

README.md

@@ -132,7 +132,8 @@ All entry points always return an instance of the pipeline.
 | `unpack()`  | Unpacks arrays into arguments for a callback. Flattens inputs if no callback provided. |             |
 | `chunk()` | Chunks the pipeline into arrays of specified length. | `array_chunk` |
 | `chunkBy()` | Chunks the pipeline into arrays with variable sizes. Size 0 produces empty arrays. | |
-| `filter()`  | Removes elements unless a callback returns true. Removes falsey values if no callback provided.  |  `array_filter`, `Where`                |
+| `select()`  | Selects elements for which the callback returns true. By default only removes `null` and `false`.  |  `array_filter`, `filter`, `Where`                |
+| `filter()`  | Alias for `select()` with `strict: false` default. Removes all falsy values like `array_filter`. |  `array_filter`                |
 | `tap()`     | Performs side effects on each element without changing the values in the pipeline. |  |
 | `skipWhile()` | Skips elements while the predicate returns true, and keeps everything after the predicate return false just once. |  | 
 | `slice()`  | Extracts a slice from the inputs. Keys are not discarded intentionally. Supports negative values for both arguments. |  `array_slice`                |
@@ -351,21 +352,23 @@ $pipeline->unpack(function ($elementOfA, $elementOfB, $elementOfC) {
 
 With iterators with unequal number of elements, missing elements are left as nulls.
 
-## `$pipeline->filter()`
+## `$pipeline->select()`
 
-Takes a filter callback not unlike that of `array_filter`.
+Selects elements for which the callback returns true. `filter()` is an alias with `strict: false` default.
 
 ```php
-$pipeline->filter(function ($item) {
+$pipeline->select(function ($item) {
     return $item->isGood() && $item->amount > 0;
 });
 ```
 
-The pipeline has a default callback with the same effect as in `array_filter`: it'll remove all falsy values.
+By default, `select()` only removes `null` and `false` values.
 
-With the optional `strict` parameter, it only removes strictly `null` or `false`:
+With the optional `strict: false` parameter, it removes all falsy values like `array_filter`:
 ```php
-$pipeline->filter(strict: true);
+$pipeline->select(strict: false);
+// Or use filter() which defaults to non-strict:
+$pipeline->filter();
 ```
 
 ## `$pipeline->slice()`

src/Standard.php

@@ -486,7 +486,7 @@ private static function applyOnce(iterable $previous, callable $func): Generator
     }
 
     /**
-     * Removes elements unless a callback returns true.
+     * Selects elements for which the callback returns true.
      *
      * With no callback drops all null and false values (not unlike array_filter does by default).
      *
@@ -496,7 +496,7 @@ private static function applyOnce(iterable $previous, callable $func): Generator
      * @phpstan-self-out self<TKey, TValue>
      * @return Standard<TKey, TValue>
      */
-    public function filter(?callable $func = null, bool $strict = false): self
+    public function select(?callable $func = null, bool $strict = true): self
     {
         // No-op: an empty array or null.
         if ($this->empty()) {
@@ -517,6 +517,24 @@ public function filter(?callable $func = null, bool $strict = false): self
         return $this;
     }
 
+    /**
+     * Removes elements unless a callback returns true. Alias for select().
+     *
+     * With no callback drops all null and false values (not unlike array_filter does by default).
+     *
+     * @see select()
+     *
+     * @param null|callable(TValue): bool $func A callback that accepts a single value and returns a boolean value.
+     * @param bool $strict When true, only `null` and `false` are filtered out.
+     *
+     * @phpstan-self-out self<TKey, TValue>
+     * @return Standard<TKey, TValue>
+     */
+    public function filter(?callable $func = null, bool $strict = false): self
+    {
+        return $this->select($func, $strict);
+    }
+
     /**
      * Resolves a nullable predicate into a sensible non-null callable.
      */

tests/FilterTest.php tests/SelectTest.phptests/FilterTest.php renamed to tests/SelectTest.php

@@ -23,6 +23,7 @@
 use ArrayIterator;
 use PHPUnit\Framework\TestCase;
 use Pipeline\Standard;
+use PHPUnit\Framework\Attributes\DataProvider;
 
 use function iterator_to_array;
 use function Pipeline\fromValues;
@@ -33,7 +34,7 @@
  *
  * @internal
  */
-final class FilterTest extends TestCase
+final class SelectTest extends TestCase
 {
     private const NON_STRICT_FALSE_VALUES = [
         0,
@@ -46,20 +47,20 @@ final class FilterTest extends TestCase
     public function testStandardStringFunctions(): void
     {
         $pipeline = new Standard(new ArrayIterator([1, 2, 'foo', 'bar']));
-        $pipeline->filter('is_int');
+        $pipeline->select('is_int');
 
         $this->assertSame([1, 2], iterator_to_array($pipeline));
     }
 
     public function testStandardFunctions(): void
     {
         $pipeline = new Standard(new ArrayIterator([1, 2, 'foo', 'bar']));
-        $pipeline->filter(is_int(...));
+        $pipeline->select(is_int(...));
 
         $this->assertSame([1, 2], iterator_to_array($pipeline));
     }
 
-    public function testFilterAnyFalseValueDefaultCallback(): void
+    public function testSelectAnyFalseValueDefaultCallback(): void
     {
         $pipeline = map(function () {
             yield false;
@@ -71,12 +72,12 @@ public function testFilterAnyFalseValueDefaultCallback(): void
             yield null;
         });
 
-        $pipeline->filter();
+        $pipeline->select(strict: false);
 
         $this->assertCount(0, $pipeline->toList());
     }
 
-    public function testFilterAnyFalseValueDefaultCallbackStrict(): void
+    public function testSelectAnyFalseValueDefaultCallbackStrict(): void
     {
         $pipeline = map(function () {
             yield false;
@@ -88,12 +89,12 @@ public function testFilterAnyFalseValueDefaultCallbackStrict(): void
             yield null;
         });
 
-        $pipeline->filter(strict: true);
+        $pipeline->select();
 
         $this->assertCount(5, $pipeline->toList());
     }
 
-    public function testFilterAnyFalseValueCustomCallback(): void
+    public function testSelectAnyFalseValueCustomCallback(): void
     {
         $pipeline = map(function () {
             yield false;
@@ -106,12 +107,12 @@ public function testFilterAnyFalseValueCustomCallback(): void
             yield 1;
         });
 
-        $pipeline->filter('intval', strict: false);
+        $pipeline->select('intval', strict: false);
 
         $this->assertSame([1], $pipeline->toList());
     }
 
-    public function testFilterStrictMode(): void
+    public function testSelectStrictMode(): void
     {
         $pipeline = map(function () {
             yield false;
@@ -120,12 +121,12 @@ public function testFilterStrictMode(): void
             yield from self::NON_STRICT_FALSE_VALUES;
         });
 
-        $pipeline->filter(strict: true);
+        $pipeline->select(strict: true);
 
         $this->assertSame(self::NON_STRICT_FALSE_VALUES, $pipeline->toList());
     }
 
-    public function testFilterStrictModeWithPredicate(): void
+    public function testSelectStrictModeWithPredicate(): void
     {
         $pipeline = map(function () {
             yield false;
@@ -134,23 +135,62 @@ public function testFilterStrictModeWithPredicate(): void
             yield from self::NON_STRICT_FALSE_VALUES;
         });
 
-        $pipeline->filter(fn($value) => $value, strict: true);
+        $pipeline->select(fn($value) => $value, strict: true);
 
         $this->assertSame(self::NON_STRICT_FALSE_VALUES, $pipeline->toList());
     }
 
-    public function testFilterNonStrictMode(): void
+    public function testSelectNonStrictMode(): void
     {
         $pipeline = fromValues(false, null, '');
-        $pipeline->filter(strict: false);
+        $pipeline->select(strict: false);
         $this->assertCount(0, $pipeline);
     }
 
-    public function testFilterUnprimed(): void
+    public function testSelectUnprimed(): void
     {
         $pipeline = new Standard();
-        $pipeline->filter()->unpack();
+        $pipeline->select()->unpack();
 
         $this->assertSame([], $pipeline->toList());
     }
+
+    public function testFilterIsNotStrictByDefault(): void
+    {
+        $pipeline = $this->getMockBuilder(Standard::class)
+            ->setConstructorArgs([[1]])
+            ->onlyMethods(['select'])
+            ->getMock();
+
+        $pipeline->expects($this->once())
+            ->method('select')
+            ->with(null, false)
+            ->willReturn($pipeline);
+
+        $pipeline->filter();
+    }
+
+    public static function provideFilterIsEquivalentToSelect(): iterable
+    {
+        yield [null, false];
+        yield [null, true];
+        yield [fn($value) => true, false];
+        yield [fn($value) => true, true];
+    }
+
+    #[DataProvider('provideFilterIsEquivalentToSelect')]
+    public function testFilterIsEquivalentToSelect(?callable $func, bool $strict): void
+    {
+        $pipeline = $this->getMockBuilder(Standard::class)
+            ->setConstructorArgs([[1]])
+            ->onlyMethods(['select'])
+            ->getMock();
+
+        $pipeline->expects($this->once())
+            ->method('select')
+            ->with($func, $strict)
+            ->willReturn($pipeline);
+
+        $pipeline->filter($func, $strict);
+    }
 }