From fdffbd00fb4bc273ed42a71a063ade538513f224 Mon Sep 17 00:00:00 2001 From: ignace nyamagana butera Date: Thu, 22 Aug 2024 23:23:14 +0200 Subject: [PATCH] Update the documentation to add escape parameter warnings --- README.md | 4 +++ docs/9.0/connections/controls.md | 11 ++++++--- docs/9.0/connections/index.md | 42 ++++++++++++++++++++++++++++++++ docs/9.0/index.md | 5 ++++ 4 files changed, 59 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index c89992b0..e5f3c701 100644 --- a/README.md +++ b/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). diff --git a/docs/9.0/connections/controls.md b/docs/9.0/connections/controls.md index 30e9054b..7b7ef503 100644 --- a/docs/9.0/connections/controls.md +++ b/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. + +

Starting with version PHP8.4 using this method with +anything other than the empty string will trigger a PHP deprecation notice! +see Deprecation for PHP8.4 and +CSV and PHP8.4 for more information. +

### Description @@ -75,9 +82,7 @@ $escape = $csv->getEscape(); //returns "\" ```

The default escape character is \.

-

Since version 9.2.0 you can provide an empty string for the escape character to enable better RFC4180 compliance.

-

setEscape will throw a Exception exception if the submitted string length is not equal to 1 byte or an empty string.

```php diff --git a/docs/9.0/connections/index.md b/docs/9.0/connections/index.md index a8eb1447..1d385af9 100644 --- a/docs/9.0/connections/index.md +++ b/docs/9.0/connections/index.md @@ -33,6 +33,48 @@ if (!ini_get('auto_detect_line_endings')) {

auto_detect_line_endings is deprecated since PHP 8.1; and will be removed in PHP 9.0

+## 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. diff --git a/docs/9.0/index.md b/docs/9.0/index.md index c01f99c1..0050a351 100644 --- a/docs/9.0/index.md +++ b/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')