Update documentation with the new feature

CHANGELOG.md

@@ -10,11 +10,12 @@ All Notable changes to `Csv` will be documented in this file
 
 ### Deprecated
 
-- None
+- Using the `$header` argument on `Statement::process` is deprecated and will be removed in
+the next version. Use `TabularDataReader::getRecords` on the returned value instead.
 
 ### Fixed
 
-- None
+- The optional `$header` argument for `TabularDataReader;;getRecords` becomes a full mapper between the records column offset and the column names [#498](https://github.com/thephpleague/csv/issues/498)
 
 ### Removed
 

docs/9.0/reader/index.md

@@ -187,6 +187,41 @@ foreach ($records as $offset => $record) {
 
 <p class="message-warning">In both cases, if the header record contains non-unique string values, a <code>Exception</code> exception is triggered.</p>
 
+<p class="message-notice">since <code>9.12.0</code> the optional <code>$header</code> is a full mapper</p>
+
+The argument now links the records column offset to a specific column name. In other words this means
+that the array key which MUST be a positive integer or `0` will correspond to the CSV column offset
+and its value will represent its header value.
+
+This means that you can re-arrange the column order as well as removing or adding column to the returned iterator.
+Added column will only contain the `null` value.
+
+Here's an example of the new behaviour.
+
+```php
+use League\Csv\Reader;
+
+$csv = <<<CSV
+Abel,14,M,2004
+Abiga,6,F,2004
+Aboubacar,8,M,2004
+Aboubakar,6,M,2004
+CSV;
+
+$reader = Reader::createFromString($csv);
+$records = $reader->getRecords([3 => 'Year', 0 => 'Firstname', 4 => 'Yolo']);
+var_dump([...$records][0]);
+//returns something like this
+// array:4 [
+//     "Year" => "2004",
+//     "Firstname" => "Abel",
+//     "Yolo" => null,
+//  ]
+```
+
+As you can see the `Count` column is missing, the `Year` and `Firstname` columns are re-arranged but
+present and the extra `Yolo` column is added with the value `null`
+
 ### Using the IteratorAggregate interface
 
 Because the `Reader` class implements the `IteratorAggregate` interface you can directly iterate over each record using the `foreach` construct and an instantiated `Reader` object.

docs/9.0/reader/resultset.md

@@ -97,6 +97,42 @@ foreach ($records as $record) {
 }
 ```
 
+<p class="message-notice">since <code>9.12.0</code> the optional <code>$header</code> is a full mapper</p>
+
+The argument now links the records column offset to a specific column name. In other words this means
+that the array key which MUST be a positive integer or `0` will correspond to the CSV column offset
+and its value will represent its header value.
+
+This means that you can re-arrange the column order as well as removing or adding column to the returned iterator.
+Added column will only contain the `null` value.
+
+Here's an example of the new behaviour.
+
+```php
+use League\Csv\Reader;
+
+$csv = <<<CSV
+Abel,14,M,2004
+Abiga,6,F,2004
+Aboubacar,8,M,2004
+Aboubakar,6,M,2004
+CSV;
+
+$reader = Reader::createFromString($csv);
+$resultSet = Statement::create()->process($reader);
+$records = $resultSet->getRecords([3 => 'Year', 0 => 'Firstname', 4 => 'Yolo']);
+var_dump([...$records][0]);
+//returns something like this
+// array:4 [
+//     "Year" => "2004",
+//     "Firstname" => "Abel",
+//     "Yolo" => null,
+//  ]
+```
+
+As you can see the `Count` column is missing, the `Year` and `Firstname` columns are re-arranged but
+present and the extra `Yolo` column is added with the value `null`
+
 ### Usage with the header
 
 If the `ResultSet::getHeader` is not an empty `array` the found records keys will contain the returned values.

docs/9.0/reader/statement.md

@@ -105,6 +105,10 @@ $records = $stmt->process($reader);
 
 Just like the `Reader:getRecords`, the `Statement::process` method takes an optional `$header` argument to allow mapping CSV field names to a user defined header record.
 
+<p class="message-warning">Using the <code>$header</code> argument is deprecated since version <code>9.12.0</code>,
+use instead the <code>TabularDataReader::getRecords</code> method instead on the returned value.
+A <code>E_USER_DEPRECATED</code> notice will be triggered if the argument is used.</p>
+
 ```php
 use League\Csv\Reader;
 use League\Csv\Statement;

src/Statement.php

@@ -20,6 +20,8 @@
 
 use function array_reduce;
 
+use const E_USER_DEPRECATED;
+
 /**
  * Criteria to filter a {@link TabularDataReader} object.
  */
@@ -120,6 +122,10 @@ public function limit(int $limit): self
      */
     public function process(TabularDataReader $tabular_data, array $header = []): TabularDataReader
     {
+        if ([] !== $header) {
+            @trigger_error('Since league\csv 9.12.0: the $header argument is deprecated and will be removed in the next major release; Please use getRecords on the returned TabularDataReader', E_USER_DEPRECATED);
+        }
+
         if ([] === $header) {
             $header = $tabular_data->getHeader();
         }