Simplify Reader and Writer instantiation

Author: nyamsprod

CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All Notable changes to `Csv` will be documented in this file
 
+## [Next](https://github.com/thephpleague/csv/compare/9.26.0...master) - TBD
+
+### Added
+
+- `AbstractCsv::from` and `AbstractCsv::fromString` to simplify instantiating `Reader` and `Writer` instance.
+- `Stream::from` and `Stream::fromString` to simplify internal instantiation of `Stream` instances.
+
+### Deprecated
+
+-  `AbstractCsv::createFromString` use `AbstractCsv::fromString` instead
+-  `AbstractCsv::createFromStream` use `AbstractCsv::from` instead
+-  `AbstractCsv::createFromFileObject` use `AbstractCsv::from` instead
+-  `Stream::createFromResource` use `Stream::from` instead
+-  `Stream::createFromString` use `Stream::fromString` instead
+
+### Fixed
+
+- `None
+
+### Remove
+
+- None
+
 ## [9.26.0](https://github.com/thephpleague/csv/compare/9.25.0...9.26.0) - 2025-10-01
 
 ### Added

docs/9.0/connections/instantiation.md

@@ -5,11 +5,84 @@ title: Loading CSV documents
 
 # Document loading
 
-Because CSV documents come in different forms we use named constructors to offer several ways to load them.
+Because CSV documents come in different forms, we use named constructors to offer several ways to load them.
 
+## Modern instantiation public API
+
+<p class="message-notice">This new API is introduced in version <code>9.27.0</code></p>
+
+### Loading from a string
+
+```php
+public static AbstractCsv::fromString(string $content = ''): self
+```
+
+Create a new object from a given string.
+
+```php
+use League\Csv\Reader;
+use League\Csv\Writer;
+
+$reader = Reader::fromString('john,doe,[email protected]');
+$writer = Writer::fromString('john,doe,[email protected]');
+```
+
+<p class="message-notice">The <code>$content</code> argument default value is an empty string to ease usage.</p>
+
+## Loading from a file or a stream
+
+```php
+public static AbstractCsv::from(
+    SplFileInfo|SplFileObject|resource|string $filename,
+    string $mode = 'r+',
+    resource $context = null
+): self
+```
+
+If an `string` or a `SplFileInfo` object is given as the `$filename` argument, a new instance
+is created *à la* `fopen` and the `$mode` and the `$context` parameters are taking into account.
+
+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>:
+<ul>
+    <li><code>createFromPath()</code></li>
+    <li><code>createFromStream()</code></li>
+    <li><code>createFromFileObject()</code></li>
+</ul>
+</div>
+
+```php
+use League\Csv\Reader;
+use League\Csv\Writer;
+
+$reader = Reader::from('/path/to/your/csv/file.csv', 'r');
+$writer = Writer::from('/path/to/your/csv/file.csv', 'w');
+
+$reader = Reader::from(fopen('/path/to/the/file.csv', 'r+'));
+$writer = Writer::from(tmpfile());
+
+$reader = Reader::from(new SplFileInfo('/path/to/your/csv/file.csv'));
+$writer = Writer::from(new SplTempFileObject());
+```
+
+<div class="message-notice">
+The <code>$mode</code> argument defaults to:
+<ul>
+<li><code>r+</code> for the <code>Writer</code> class</li>
+<li><code>r</code> for the <code>Reader</code> class</li>
+</ul>
+</div>
+
+<p class="message-notice">The method allows loading non-seekable stream resource.</p>
+
+## Deprecated public API
+
+<p class="message-warning">The following methods are all deprecated as of version <code>9.27.0</code></p>
 <p class="message-warning">Since version <code>9.1.0</code> non-seekable CSV documents can be used but <strong>exceptions will be thrown if features requiring a seekable CSV document are used.</strong></p>
 
-## Loading from a string
+### Loading from a string
 
 ```php
 public static AbstractCsv::createFromString(string $content = ''): self
@@ -27,7 +100,7 @@ $writer = Writer::createFromString('john,doe,[email protected]');
 
 <p class="message-notice">Since version <code>9.2.0</code> the <code>$content</code> argument default value is an empty string to ease usage.</p>
 
-## Loading from a file path
+### Loading from a file path
 
 ```php
 public static AbstractCsv::createFromPath(
@@ -55,7 +128,7 @@ Starting with version <code>9.1.0</code>, <code>$open_mode</code> defaults to:
 </ul>
 </div>
 
-## Loading from a resource stream
+### Loading from a resource stream
 
 ```php
 public static AbstractCsv::createFromStream(resource $stream): self
@@ -73,7 +146,7 @@ $writer = Writer::createFromStream(tmpfile());
 
 <p class="message-notice">Prior to version <code>9.1.0</code>, the method would throw a <code>League\Csv\Exception</code> for a non-seekable stream resource.</p>
 
-## Loading from a SplFileObject object
+### Loading from a SplFileObject object
 
 ```php
 public static AbstractCsv::createFromFileObject(SplFileObject $file): self
@@ -103,8 +176,8 @@ Once instantiated, the `getPathname` method returns the pathname of the underlyi
 use League\Csv\Reader;
 use League\Csv\Writer;
 
-Reader::createFromFileObject(new SplFileObject('/path/to/your/csv/file.csv'))->getPathname();
+Reader::from(new SplFileObject('/path/to/your/csv/file.csv'))->getPathname();
 //returns '/path/to/your/csv/file.csv'
-Writer::createFromFileObject(new SplTempFileObject())->getPathname();
+Writer::from(new SplTempFileObject())->getPathname();
 //returns php://temp
 ```

src/AbstractCsv.php

@@ -18,12 +18,16 @@
 use Generator;
 use InvalidArgumentException;
 use RuntimeException;
+use SplFileInfo;
 use SplFileObject;
 use Stringable;
 use Throwable;
+use TypeError;
 
 use function filter_var;
 use function get_class;
+use function gettype;
+use function is_resource;
 use function rawurlencode;
 use function sprintf;
 use function str_replace;
@@ -79,42 +83,30 @@ public function __clone()
         throw UnavailableStream::dueToForbiddenCloning(static::class);
     }
 
-    /**
-     * Returns a new instance from a SplFileObject.
-     */
-    public static function createFromFileObject(SplFileObject $file): static
-    {
-        return new static($file);
-    }
-
-    /**
-     * Returns a new instance from a PHP resource stream.
-     *
-     * @param resource $stream
-     */
-    public static function createFromStream($stream): static
-    {
-        return new static(Stream::createFromResource($stream));
-    }
-
     /**
      * Returns a new instance from a string.
      */
-    public static function createFromString(Stringable|string $content = ''): static
+    public static function fromString(Stringable|string $content = ''): static
     {
-        return new static(Stream::createFromString($content));
+        return new static(Stream::fromString($content));
     }
 
     /**
      * Returns a new instance from a file path.
      *
-     * @param resource|null $context the resource context
+     * @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 createFromPath(string $path, string $open_mode = 'r+', $context = null): static
+    public static function from($filename, string $mode = 'r+', $context = null): static
     {
-        return new static(Stream::createFromPath($path, $open_mode, $context));
+        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)),
+        };
     }
 
     /**
@@ -621,4 +613,65 @@ public function addStreamFilter(string $filtername, ?array $params = null): stat
 
         return $this->appendStreamFilterOnWrite($filtername, $params);
     }
+
+    /**
+     * DEPRECATION WARNING! This method will be removed in the next major point release.
+     * @codeCoverageIgnore
+     * @deprecated since version 9.27.0
+     *
+     * Returns a new instance from a SplFileObject.
+     */
+    #[Deprecated(message:'use League\Csv\AbstractCsv::from() instead', since:'league/csv:9.27.0')]
+    public static function createFromFileObject(SplFileObject $file): static
+    {
+        return new static($file);
+    }
+
+    /**
+     * DEPRECATION WARNING! This method will be removed in the next major point release.
+     * @codeCoverageIgnore
+     * @deprecated since version 9.27.0
+     *
+     * Returns a new instance from a PHP resource stream.
+     *
+     * @param resource $stream
+     */
+    #[Deprecated(message:'use League\Csv\AbstractCsv::from() instead', since:'league/csv:9.27.0')]
+    public static function createFromStream($stream): static
+    {
+        is_resource($stream) || throw new TypeError('Argument passed must be a stream resource or a string, '.gettype($stream).' given.');
+
+        return new static(Stream::from($stream));
+    }
+
+    /**
+     * DEPRECATION WARNING! This method will be removed in the next major point release.
+     * @codeCoverageIgnore
+     * @deprecated since version 9.27.0
+     *
+     * Returns a new instance from a string.
+     */
+    #[Deprecated(message:'use League\Csv\AbstractCsv::fromString() instead', since:'league/csv:9.27.0')]
+    public static function createFromString(Stringable|string $content = ''): static
+    {
+        return self::fromString($content);
+    }
+
+    /**
+     * DEPRECATION WARNING! This method will be removed in the next major point release.
+     * @codeCoverageIgnore
+     * @deprecated since version 9.27.0
+     *
+     * Returns a new instance from a file path.
+     *
+     * @param non-empty-string $open_mode
+     * @param resource|null $context the resource context
+     *
+     * @throws UnavailableStream
+     */
+    #[Deprecated(message:'use League\Csv\AbstractCsv::from() instead', since:'league/csv:9.27.0')]
+    public static function createFromPath(string $path, string $open_mode = 'r+', $context = null): static
+    {
+        return new static(Stream::from($path, $open_mode, $context));
+    }
 }