From 74c020147dc768cc15867bc6d18e763c5477b973 Mon Sep 17 00:00:00 2001
From: ignace nyamagana butera <nyamsprod@gmail.com>
Date: Sun, 1 Oct 2023 08:30:09 +0200
Subject: [PATCH] Update documentation with the new feature

---
 CHANGELOG.md                 |  2 +-
 docs/9.0/reader/index.md     | 35 +++++++++++++++++++++++++++++++++++
 docs/9.0/reader/resultset.md | 36 ++++++++++++++++++++++++++++++++++++
 3 files changed, 72 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 48d79cf2..701bef71 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,7 +14,7 @@ All Notable changes to `Csv` will be documented in this file
 
 ### 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
 
diff --git a/docs/9.0/reader/index.md b/docs/9.0/reader/index.md
index cd2631ad..8a488d8e 100644
--- a/docs/9.0/reader/index.md
+++ b/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.
diff --git a/docs/9.0/reader/resultset.md b/docs/9.0/reader/resultset.md
index 241cd2c8..30d0b98b 100644
--- a/docs/9.0/reader/resultset.md
+++ b/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.