feat: update Collection::fromFile constructor (#322)

- Remove `length` parameter
- Add `consumer` parameter

BREAKING CHANGE: yes

composer.json

@@ -37,7 +37,7 @@
     ],
     "require": {
         "php": ">= 8.1",
-        "loophp/iterators": "^2.4"
+        "loophp/iterators": "^3"
     },
     "require-dev": {
         "ext-pcov": "*",

docs/pages/api.rst

@@ -47,11 +47,10 @@ fromFile
 
 Create a collection from a file.
 
-Signature: ``Collection::fromIterable(string $filepath): Collection;``
+Signature: ``Collection::fromFile(string $filepath, ?Closure $consumer = null): Collection;``
 
-.. code-block:: php
-
-    Collection::fromFile('http://loripsum.net/api');
+.. literalinclude:: code/operations/fromFile.php
+  :language: php
 
 fromGenerator
 ~~~~~~~~~~~~~

docs/pages/code/operations/fromFile.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App;
+
+use loophp\collection\Collection;
+
+include __DIR__ . '/../../../../vendor/autoload.php';
+
+// Get data from a file
+Collection::fromFile('/etc/passwd');
+
+// Get data from a URL
+Collection::fromFile('http://loripsum.net/api');
+
+// Get data from a CSV file
+Collection::fromFile('data.csv', fgetcsv(...));

src/Collection.php

@@ -358,14 +358,14 @@ public static function fromCallable(callable $callable, iterable $parameters = [
     }
 
     /**
-     * @param null|non-negative-int $length
+     * @param Closure(resource): mixed $consumer
      *
-     * @return CollectionInterface<int, string>&self<int, string>
+     * @return CollectionInterface<int, string|mixed>&self<int, string|mixed>
      */
-    public static function fromFile(string $filepath, ?int $length = 2): CollectionInterface
+    public static function fromFile(string $filepath, ?Closure $consumer = null): CollectionInterface
     {
         return new self(
-            static fn (): Generator => yield from new ResourceIteratorAggregate(fopen($filepath, 'rb'), true, $length),
+            static fn (): Generator => yield from new ResourceIteratorAggregate(fopen($filepath, 'rb'), true, $consumer),
         );
     }
 

src/CollectionDecorator.php

@@ -283,11 +283,11 @@ public static function fromCallable(callable $callable, iterable $parameters = [
     }
 
     /**
-     * @param null|non-negative-int $length
+     * @param Closure(resource): mixed $consumer
      */
-    public static function fromFile(string $filepath, ?int $length = 2): static
+    public static function fromFile(string $filepath, ?Closure $consumer = null): static
     {
-        return new static(Collection::fromFile($filepath, $length));
+        return new static(Collection::fromFile($filepath, $consumer));
     }
 
     public static function fromGenerator(Generator $generator): static

tests/fixtures/data.csv

@@ -0,0 +1,2 @@
+a,b,c
+d,e,f

tests/unit/CollectionConstructorsTest.php

@@ -107,6 +107,14 @@ public function testFromFileConstructor()
             ['a', 'b', 'c'],
             Collection::fromFile(__DIR__ . '/../fixtures/sample.txt')
         );
+
+        self::assertIdenticalIterable(
+            [['a', 'b', 'c'], ['d', 'e', 'f']],
+            Collection::fromFile(
+                __DIR__ . '/../fixtures/data.csv',
+                fgetcsv(...)
+            )
+        );
     }
 
     public function testFromGeneratorConstructor()