Improve CSV named constructor

Author: nyamsprod

docs/9.0/connections/instantiation.md

@@ -8,7 +8,9 @@ description: The different ways the package allow to load and interact with CSV
 
 Because CSV documents come in different forms, we use named constructors to offer several ways to load them.
 
-## Loading from a string
+## New API
+
+### Loading from a string
 
 <p class="message-notice">This new API is introduced in version <code>9.27.0</code></p>
 
@@ -28,7 +30,53 @@ $writer = Writer::fromString('john,doe,john.doe@example.com');
 
 <p class="message-notice">The <code>$content</code> argument default value is an empty string to ease usage.</p>
 
-## Loading from a file pointer
+### Loading from a path
+
+<div class="message-info">Since version <code>9.29.0</code></div>
+<div class="message-notice">Since version <code>9.27.0</code> the <code>createFromPath()</code> method is <strong>deprecated</strong></div>
+
+```php
+public static Reader::fromPath(SplFileInfo|string $path, string $mode = 'r', ?resource $context = null): Reader
+public static Writer::fromPath(SplFileInfo|string $path, string $mode = 'r+', ?resource $context = null): Writer
+```
+
+Creates a new object *à la* `fopen`.
+
+```php
+use League\Csv\Reader;
+use League\Csv\Writer;
+
+$reader = Reader::fromPath('/path/to/your/csv/file.csv', 'r');
+$writer = Writer::fromPath(new SplFileInfo('/path/to/your/csv/file.csv'), 'w');
+```
+
+<p class="message-warning">A <code>SplFileObject</code> does not expose its context. If it was created with one, you must pass it explicitly to the <code>$context</code> argument.
+Alternatively, you can use the <code>fromStream</code> method.</p>
+
+### Loading from stream
+
+<div class="message-info">Since version <code>9.29.0</code></div>
+<div class="message-notice">Since version <code>9.27.0</code> the <code>createFromStream()</code> and <code>createFromFileObject()</code> methods are <strong>deprecated</strong></div>
+
+```php
+public static AbstractCsv::fromStream(SplFileObject|resource $stream): self
+```
+Creates a new object from a stream resource or a streaming object.
+
+```php
+use League\Csv\Reader;
+use League\Csv\Writer;
+
+$reader = Reader::fromStream(fopen('/path/to/the/file.csv', 'r+'));
+$writer = Writer::fromStream(tmpfile());
+$reader = Reader::fromStream(new SplFileObject('/path/to/your/csv/file.csv'));
+$writer = Writer::fromStream(new SplTempFileObject());
+```
+
+The provided stream—whether a resource or a SplFileObject—is used as-is. It is the developer’s responsibility to ensure that the stream
+is valid and has the appropriate permissions; otherwise, exceptions may be thrown during use.
+
+### Loading from a file pointer
 
 <p class="message-notice">This new API is introduced in version <code>9.27.0</code></p>
 
@@ -46,7 +94,7 @@ is created *à la* `fopen` and the `$mode` and `$context` parameters are taken i
 Otherwise, when a stream resource or an `SplFileObject` instance is given, both arguments are
 ignored.
 
-<div class="message-notice">Since version <code>9.27.0</code> the following methods are <strong>deprecated</strong>:
+<div class="message-notice">Since version <code>9.27.0</code> this method can be use to replace the <strong>deprecated</strong> methods:
 <ul>
     <li><code>createFromPath()</code></li>
     <li><code>createFromStream()</code></li>

src/AbstractCsv.php

@@ -86,24 +86,6 @@ public function __clone()
         throw UnavailableStream::dueToForbiddenCloning(static::class);
     }
 
-    /**
-     * Returns a new instance from a file path.
-     *
-     * @param SplFileInfo|SplFileObject|resource|string $filename an SPL file object, a resource stream or a file path
-     * @param non-empty-string $mode the file path open mode used with a file path or a SplFileInfo object
-     * @param resource|null $context the resource context used with a file pathor a SplFileInfo object
-     *
-     * @throws UnavailableStream
-     */
-    public static function from($filename, string $mode = 'r+', $context = null): static
-    {
-        return match (true) {
-            $filename instanceof SplFileObject => new static($filename),
-            $filename instanceof SplFileInfo => new static($filename->openFile(mode: $mode, context: $context)),
-            default => new static(Stream::from($filename, $mode, $context)),
-        };
-    }
-
     /**
      * @param SplFileInfo|string $path an SPL file object, a file path or a stream URI
      * @param non-empty-string $mode the file path open mode
@@ -113,10 +95,7 @@ public static function from($filename, string $mode = 'r+', $context = null): st
      */
     public static function fromPath(SplFileInfo|string $path, string $mode = 'r', $context = null): static
     {
-        return match (true) {
-            $path instanceof SplFileInfo => static::from(filename: $path->openFile(mode: $mode, context: $context)),
-            default => static::from(filename: $path, mode: $mode, context: $context),
-        };
+        return static::from(filename: $path, mode: $mode, context: $context);
     }
 
     /**
@@ -129,8 +108,8 @@ public static function fromPath(SplFileInfo|string $path, string $mode = 'r', $c
     public static function fromStream($stream): static
     {
         if (!$stream instanceof SplFileObject) {
-            is_resource($stream) || throw new TypeError('Argument passed must be a stream resource, '.gettype($stream).' given.');
-            'stream' === ($type = get_resource_type($stream)) || throw new TypeError('Argument passed must be a stream resource, '.$type.' resource given');
+            is_resource($stream) || throw new TypeError('Argument passed must be a stream resource or an SplFileObject instance, '.gettype($stream).' given.');
+            'stream' === ($type = get_resource_type($stream)) || throw new TypeError('Argument passed must be a stream resource or an SplFileObject instance, '.$type.' resource given');
         }
 
         return static::from(filename: $stream);
@@ -144,6 +123,23 @@ public static function fromString(Stringable|string $content = ''): static
         return new static(document: Stream::fromString($content));
     }
 
+    /**
+     * Returns a new instance from a file path.
+     *
+     * @param SplFileInfo|SplFileObject|resource|string $filename an SPL file object, a resource stream or a file path
+     * @param non-empty-string $mode the file path open mode used with a file path or a SplFileInfo object
+     * @param resource|null $context the resource context used with a file pathor a SplFileInfo object
+     *
+     * @throws UnavailableStream
+     */
+    public static function from($filename, string $mode = 'r+', $context = null): static
+    {
+        return new static($filename instanceof SplFileObject
+            ? $filename
+            : Stream::from($filename, $mode, $context)
+        );
+    }
+
     /**
      * Returns the current field delimiter.
      */

src/Stream.php

@@ -16,6 +16,7 @@
 use Deprecated;
 use RuntimeException;
 use SeekableIterator;
+use SplFileInfo;
 use SplFileObject;
 use Stringable;
 use TypeError;
@@ -124,14 +125,18 @@ public function ftell(): int|false
     /**
      * Returns a new instance from a file path.
      *
-     * @param resource|string $filename
+     * @param resource|string|SplFileInfo $filename
      * @param resource|null $context
      *
      * @throws UnavailableStream if the stream resource cannot be created
      */
     public static function from($filename, string $mode = 'r', $context = null): self
     {
         $should_close_stream = false;
+        if ($filename instanceof SplFileInfo) {
+            $filename = $filename->getPathname();
+        }
+
         if (is_string($filename)) {
             $should_close_stream = true;
             /** @var resource|false $resource */