PHP 8.1: Configurable line endings for fputcsv and SplFileObject::fputcsv

PHP's built-in CSV writing functions, fputcsv and SplFileObject::fputcsv support a new parameter in PHP 8.1, to pass a customizable end-of-line character.

Prior to PHP 8.1, it was hard-coded to "\n", the Line-Feed character. This new parameter is optional, and defaults to the "\n" character, so existing applications and any code that do not explicitly set a end-of-line character continue to use "\n".

For both fputcsv and SplFileObject::fputcsv, a new optional parameter with name eol is added to the end of the parameter list.

Updated Function Stubs

- function fputcsv($stream, array $fields, string $separator = ",", string $enclosure = "\"", string $escape = "\\"): int|false {}
+ function fputcsv($stream, array $fields, string $separator = ",", string $enclosure = "\"", string $escape = "\\", string  $eol = "\n"): int|false {}

class SplFileObject {
- public function fputcsv(array $fields, string $separator = ",", string $enclosure = "\"", string $escape = "\\") {}
+ public function fputcsv(array $fields, string $separator = ",", string $enclosure = "\"", string $escape = "\\", string  $eol = "\n") {}
   // ...
}

---

Both fputcsv and SplFileObject::fputcsv functions have a rather lengthy parameter list, and it might be more readable with PHP 8.0's named parameters.
EOL characters such as \r\n and \n must be using double quotes to be interpreted as EOL characters. See Character escape sequences in PHP: New Lines

$fh = fopen('test.txt', 'w+');
$fputcsv($fh, 
    fields: [],
    eol: "\r\n",
);

---

The CSV reading functions, fgetcsv and SplFileObject::fgetcsv can handle files with any mix of line endings: \r, \n, and \r\n.

Backwards Compatibility Impact

The new parameter eol is added to the end of the parameter list in both fputcsv and SplFileObject::fputcsv functions.

The default value of the parameter is also set to "\n", which was the assumed default prior to PHP 8.1 too. This ensures that any existing applications or new applications continue to use the "\n" character as their line-endings.

---

However, note that any application code that extends the SplFileObject class, and declares a fputcsv method will get LSP errors because from PHP 8.0, class inheritance signature mismatches causes a fatal error.

class Foo extends SplFileObject {
    public function fputcsv(array $fields, string $separator = ",", string $enclosure = "\"", string $escape = "\\") {}
}

Fatal error: Declaration of Foo::fputcsv(array $fields, string $separator = ',', string $enclosure = '"', string $escape = '\') must be compatible with SplFileObject::fputcsv(array $fields, string $separator = ",", string $enclosure = "\"", string $escape = "\\", string $eol = "\n") in ... on line ...

To avert this, any classes that extend SplFileObject::fputcsv method must be updated to accommodate the new eol parameter. This change will be backwards-compatible, because adding a parameter in a child method does not violate Liskov Substitution Principle .

class Foo extends SplFileObject {
-   public function fputcsv(array $fields, string $separator = ",", string $enclosure = "\"", string $escape = "\\") {}
+   public function fputcsv(array $fields, string $separator = ",", string $enclosure = "\"", string $escape = "\\", string  $eol = "\n") {}
}

---

Implementation