Update the documentation to add escape parameter warnings

README.md

@@ -51,6 +51,10 @@ composer require league/csv:^9.0
 
 ## Configuration
 
+> [!WARNING]
+> **Starting with PHP8.4 Deprecation notices will be trigger if you do not explicitly use the empty string as the escape parameter.**
+> see [Deprecation for PHP8.4](https://wiki.php.net/rfc/deprecations_php_8_4#deprecate_proprietary_csv_escaping_mechanism) and [CSV and PHP8.4](https://nyamsprod.com/blog/csv-and-php8-4/)
+
 > [!TIP]
 > If your CSV document was created or is read on a **Legacy Macintosh computer**, add the following lines before 
 using the library to help [PHP detect line ending](http://php.net/manual/en/function.fgetcsv.php#refsect1-function.fgetcsv-returnvalues).

docs/9.0/connections/controls.md

@@ -55,7 +55,14 @@ $enclosure = $csv->getEnclosure(); //returns "|"
 
 ## The escape character
 
-This is a PHP specific control character which sometimes interferes with CSV parsing and writing. It is recommended in versions preceding `9.2.0` to never change its default value unless you do understand its usage and its consequences.
+This is a PHP specific control character which sometimes interferes with CSV parsing and writing.
+It is recommended in versions preceding `9.2.0` to never change its default value unless you do understand its usage and its consequences.
+
+<p class="message-warning">Starting with version <code>PHP8.4</code> using this method with
+anything other than the empty string will trigger a <code>PHP deprecation notice!</code>
+see <a href="https://wiki.php.net/rfc/deprecations_php_8_4#deprecate_proprietary_csv_escaping_mechanism">Deprecation for PHP8.4</a> and
+<a href="https://nyamsprod.com/blog/csv-and-php8-4/">CSV and PHP8.4</a> for more information.
+</p>
 
 ### Description
 
@@ -75,9 +82,7 @@ $escape = $csv->getEscape(); //returns "\"
 ```
 
 <p class="message-info">The default escape character is <code>\</code>.</p>
-
 <p class="message-notice">Since version <code>9.2.0</code> you can provide an empty string for the escape character to enable better <a href="https://tools.ietf.org/html/rfc4180">RFC4180</a> compliance.</p>
-
 <p class="message-warning"><code>setEscape</code> will throw a <code>Exception</code> exception if the submitted string length is not equal to <code>1</code> byte or an empty string.</p>
 
 ```php

docs/9.0/connections/index.md

@@ -33,6 +33,48 @@ if (!ini_get('auto_detect_line_endings')) {
 
 <p class="message-warning"><code>auto_detect_line_endings</code> is deprecated since <code>PHP 8.1</code>; and will be removed in <code>PHP 9.0</code></p>
 
+## Deprecation Notice
+
+Starting with PHP8.4+, because the library is buit using the native CSV features of PHP
+your code may start emitting deprecation notices. To avoid those deprecations you
+must explicitly set the escape control character to be the empty string as
+shown in the example below:
+
+```php
+use League\Csv\Reader;
+use League\Csv\Writer;
+
+$csv = Reader::createFromPath('/path/to/file.csv', 'r');
+$csv->setEscape(''); //required in PHP8.4+
+
+$writer = Writer::createFromString();
+$writer->setEscape(''); //required in PHP8.4+
+```
+
+Doing so will prevent any deprecation notice. Of course, you are required to review on a
+case-by-case basis these changes as they may introduce some bugs while reading existing
+CSV documents. A way to mitigate these issues is to re-encode CSV documents that are broken
+to remove the escape character usage in them.
+
+```php
+use League\Csv\Reader;
+use League\Csv\Writer;
+
+$csv = Reader::createFromPath('/path/to/file_with_escape_character.csv', 'r');
+$writer = Writer::createFromPath('/path/to/file_without_escape_character.csv', 'w');
+$writer->setEscape('');
+$writer->setDelimiter($csv->getDelimiter());
+$writer->setEnclosure($csv->getEnclosure());
+$writer->insertAll($csv); // deprecation notice from reading the old file will be emitted!
+```
+
+The following example highlights a simple strategy to re-encode your old CSV documents.
+After that, you can use the new document by setting the escape character to the
+empty string, and you will never get any deprecation notice again.
+
+Of course, it is highly recommended to adapt this script so that it can fit in
+your application lifecycle.
+
 ## Exceptions
 
 The default exception class thrown while using this library is `League\Csv\Exception` which extends PHP `Exception` class.

docs/9.0/index.md

@@ -25,6 +25,7 @@ use League\Csv\Statement;
 
 $csv = Reader::createFromPath('/path/to/your/csv/file.csv', 'r');
 $csv->setHeaderOffset(0); //set the CSV header offset
+$csv->setEscape(''); //required in PHP8.4+ to avoid deprecation notices
 
 //get 25 records starting from the 11th row
 $stmt = Statement::create()
@@ -57,6 +58,7 @@ $sth->execute();
 
 // We create the CSV into memory
 $csv = Writer::createFromFileObject(new SplTempFileObject());
+$csv->setEscape(''); //required in PHP8.4+ to avoid deprecation notices
 
 // We insert the CSV header
 $csv->insertOne(['firstname', 'lastname', 'email']);
@@ -90,6 +92,7 @@ $sth = $dbh->prepare(
 // with the header record and remove it from the iteration
 $csv = Reader::createFromPath('/path/to/your/csv/file.csv')
     ->setHeaderOffset(0)
+    ->setEscape('') //required in PHP8.4+ to avoid deprecation notices
 ;
 
 foreach ($csv as $record) {
@@ -112,6 +115,7 @@ use League\Csv\CharsetConverter;
 
 $csv = Reader::createFromPath('/path/to/your/csv/file.csv', 'r');
 $csv->setHeaderOffset(0);
+$csv->setEscape(''); //required in PHP8.4+ to avoid deprecation notices
 
 $inputBom = Bom::tryFrom($csv->getInputBOM());
 if ($inputBom instanceof Bom && !$inputBom->isUtf8()) {
@@ -134,6 +138,7 @@ use League\Csv\Reader;
 $csv = Reader::createFromPath('/path/to/prenoms.csv', 'r')
 $csv->setDelimiter(';');
 $csv->setHeaderOffset(0);
+$csv->setEscape(''); //required in PHP8.4+ to avoid deprecation notices
 
 $converter = (new XMLConverter())
     ->rootElement('csv')