Skip to content

Commit

Permalink
Update the documentation to add escape parameter warnings
Browse files Browse the repository at this point in the history
  • Loading branch information
nyamsprod committed Aug 22, 2024
1 parent 9510a41 commit 346fa8c
Show file tree
Hide file tree
Showing 2 changed files with 12 additions and 3 deletions.
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
11 changes: 8 additions & 3 deletions docs/9.0/connections/controls.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand Down

0 comments on commit 346fa8c

Please sign in to comment.