Prepare new release

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 All Notable changes to `Csv` will be documented in this file
 
-## [Next](https://github.com/thephpleague/csv/compare/9.17.0...master) - TBD
+## [9.18.0](https://github.com/thephpleague/csv/compare/9.17.0...9.18.0) - 2024-10-18
 
 ### Added
 
@@ -12,6 +12,7 @@ All Notable changes to `Csv` will be documented in this file
 ### Deprecated
 
 - `League\Csv\AbstractCsv::output` use `League\Csv\AbstractCsv::download` instead
+- `League\Csv\FragmentFinder` and derived methods are marked as **experimental** as their results will be changed in the next major version.
 
 ### Fixed
 

docs/9.0/reader/statement.md

@@ -409,6 +409,10 @@ documents or `TabularDataReader` instances if needed.
 ## FragmentFinder
 
 <p class="message-info">This mechanism is introduced with version <code>9.12.0</code>.</p>
+<p class="message-warning">This implementation is marked as experimetal since version <code>9.12.0</code>.
+The public API is stable but the implementation and returned value will change in the next version to
+take into account edge cases and improve error and selection handling. It is recommended to avoid using
+the current implementation <strong>or</strong> restrict its usage for simple selection in version 9.</p>
 
 The second mechanism is based on [RFC7111](https://www.rfc-editor.org/rfc/rfc7111) and allow selecting
 part of your document according to its rows, columns or cells coordinates. The RFC, and thus, our class

src/FragmentFinder.php

@@ -25,7 +25,11 @@
 use const FILTER_VALIDATE_INT;
 
 /**
+ * EXPERIMENTAL WARNING! This class implementation will change in the next major point release.
+ *
  * @phpstan-type selection array{selection:string, start:int<-1, max>, end:?int, length:int, columns:array<int>}
+ *
+ * @experimental
  */
 class FragmentFinder
 {
@@ -42,8 +46,13 @@ public static function create(): self
     }
 
     /**
-     * @throws SyntaxError
+     * EXPERIMENTAL WARNING! This method implementation will change in the next major point release.
      *
+     * Extract all found fragment identifiers for the specifield tabular data
+     *
+     * @experimental since version 9.12.0
+     *
+     * @throws SyntaxError
      * @return iterable<int, TabularDataReader>
      */
     public function findAll(string $expression, TabularDataReader $tabularDataReader): iterable
@@ -52,6 +61,12 @@ public function findAll(string $expression, TabularDataReader $tabularDataReader
     }
 
     /**
+     * EXPERIMENTAL WARNING! This method implementation will change in the next major point release.
+     *
+     * Extract the first found fragment identifier of the tabular data or returns null
+     *
+     * @experimental since version 9.12.0
+     *
      * @throws SyntaxError
      */
     public function findFirst(string $expression, TabularDataReader $tabularDataReader): ?TabularDataReader
@@ -65,6 +80,12 @@ public function findFirst(string $expression, TabularDataReader $tabularDataRead
     }
 
     /**
+     * EXPERIMENTAL WARNING! This method implementation will change in the next major point release.
+     *
+     * Extract the first found fragment identifier of the tabular data or fail
+     *
+     * @experimental since version 9.12.0
+     *
      * @throws SyntaxError
      * @throws FragmentNotFound if the expression can not be parsed
      */

src/Reader.php

@@ -411,17 +411,42 @@ public function sorted(Query\Sort|Closure $orderBy): TabularDataReader
         return Statement::create()->orderBy($orderBy)->process($this);
     }
 
+    /**
+     * EXPERIMENTAL WARNING! This method implementation will change in the next major point release.
+     *
+     * Extract all found fragment identifiers for the specifield tabular data
+     *
+     * @experimental since version 9.12.0
+     *
+     * @throws SyntaxError
+     * @return iterable<int, TabularDataReader>
+     */
     public function matching(string $expression): iterable
     {
         return FragmentFinder::create()->findAll($expression, $this);
     }
 
+    /**
+     * EXPERIMENTAL WARNING! This method implementation will change in the next major point release.
+     *
+     * Extract the first found fragment identifier of the tabular data or returns null
+     *
+     * @experimental since version 9.12.0
+     *
+     * @throws SyntaxError
+     */
     public function matchingFirst(string $expression): ?TabularDataReader
     {
         return FragmentFinder::create()->findFirst($expression, $this);
     }
 
     /**
+     * EXPERIMENTAL WARNING! This method implementation will change in the next major point release.
+     *
+     * Extract the first found fragment identifier of the tabular data or fail
+     *
+     * @experimental since version 9.12.0
+     *
      * @throws SyntaxError
      * @throws FragmentNotFound
      */

src/ResultSet.php

@@ -259,17 +259,42 @@ public function select(string|int ...$columns): TabularDataReader
         return new self(new MapIterator($this, $callback), $hasHeader ? $header : []);
     }
 
+    /**
+     * EXPERIMENTAL WARNING! This method implementation will change in the next major point release.
+     *
+     * Extract all found fragment identifiers for the specifield tabular data
+     *
+     * @experimental since version 9.12.0
+     *
+     * @throws SyntaxError
+     * @return iterable<int, TabularDataReader>
+     */
     public function matching(string $expression): iterable
     {
         return FragmentFinder::create()->findAll($expression, $this);
     }
 
+    /**
+     * EXPERIMENTAL WARNING! This method implementation will change in the next major point release.
+     *
+     * Extract the first found fragment identifier of the tabular data or returns null
+     *
+     * @experimental since version 9.12.0
+     *
+     * @throws SyntaxError
+     */
     public function matchingFirst(string $expression): ?TabularDataReader
     {
         return FragmentFinder::create()->findFirst($expression, $this);
     }
 
     /**
+     * EXPERIMENTAL WARNING! This method implementation will change in the next major point release.
+     *
+     * Extract the first found fragment identifier of the tabular data or fail
+     *
+     * @experimental since version 9.12.0
+     *
      * @throws SyntaxError
      * @throws FragmentNotFound
      */