From 73007ad9889ca2a3d85b0a710b55deb44ac370cc Mon Sep 17 00:00:00 2001 From: Gina Peter Banyard Date: Tue, 19 Nov 2024 23:11:44 +0000 Subject: [PATCH] PHP 8.4: CSV related changes and deprecations (#4093) Co-authored-by: Christoph M. Becker --- reference/filesystem/functions/fgetcsv.xml | 59 +++++++++--- reference/filesystem/functions/fputcsv.xml | 69 ++++++-------- reference/spl/splfileobject/fgetcsv.xml | 60 +++++++++---- reference/spl/splfileobject/fputcsv.xml | 75 ++++++---------- reference/spl/splfileobject/getcsvcontrol.xml | 18 ++-- reference/spl/splfileobject/setcsvcontrol.xml | 66 ++++++-------- reference/strings/functions/str-getcsv.xml | 89 ++++++++----------- 7 files changed, 217 insertions(+), 219 deletions(-) diff --git a/reference/filesystem/functions/fgetcsv.xml b/reference/filesystem/functions/fgetcsv.xml index d0f5b40c4437..279785ed00f6 100644 --- a/reference/filesystem/functions/fgetcsv.xml +++ b/reference/filesystem/functions/fgetcsv.xml @@ -23,11 +23,12 @@ read. - - The locale settings are taken into account by this function. If - LC_CTYPE is e.g. en_US.UTF-8, files in - one-byte encodings may be read wrongly by this function. - + + The locale settings are taken into account by this function. + For example, data encoded in certain one-byte encodings may be parsed + incorrectly if LC_CTYPE is + en_US.UTF-8. + @@ -96,6 +97,14 @@ even meant to escape itself. + + + As of PHP 8.4.0, depending on the default value of + escape is deprecated. + It needs to be provided explicitly either positionally or by the use + of named arguments. + + @@ -118,6 +127,19 @@ ¬e.line-endings; + + &reftitle.errors; + + Throws a ValueError if + separator or enclosure + is not one byte long. + + + Throws a ValueError if + escape is not one byte long or the empty string. + + + &reftitle.changelog; @@ -130,6 +152,13 @@ + + 8.4.0 + + Relying on the default value of escape is now + deprecated. + + 8.0.0 @@ -178,15 +207,17 @@ if (($handle = fopen("test.csv", "r")) !== FALSE) { &reftitle.seealso; - - - str_getcsv - explode - file - pack - fputcsv - - + + fputcsv + str_getcsv + SplFileObject::fgetcsv + SplFileObject::fputcsv + SplFileObject::setCsvControl + SplFileObject::getCsvControl + explode + file + pack + diff --git a/reference/filesystem/functions/fputcsv.xml b/reference/filesystem/functions/fputcsv.xml index 732e2ae79e42..f3a94fb1b1ce 100644 --- a/reference/filesystem/functions/fputcsv.xml +++ b/reference/filesystem/functions/fputcsv.xml @@ -1,6 +1,6 @@ - + fputcsv Format line as CSV and write to file pointer @@ -19,8 +19,9 @@ fputcsv formats a line (passed as a - fields array) as CSV and writes it (terminated by a - newline) to the specified file stream. + fields array) as CSV and writes it + (terminated by a eol) to the specified + stream. @@ -42,34 +43,15 @@ - - separator - - - The optional separator parameter sets the field - delimiter (one single-byte character only). - - - - - enclosure - - - The optional enclosure parameter sets the field - enclosure (one single-byte character only). - - - - - escape - - - The optional escape parameter sets the - escape character (at most one single-byte character). - An empty string ("") disables the proprietary escape mechanism. - - - + + + + + + + + + eol @@ -98,6 +80,10 @@ + + + + &reftitle.changelog; @@ -110,6 +96,9 @@ + + + 8.1.0 @@ -167,18 +156,16 @@ aaa,bbb,ccc,dddd - - &reftitle.notes; - ¬e.line-endings; - - &reftitle.seealso; - - - fgetcsv - - + + fgetcsv + str_getcsv + SplFileObject::fgetcsv + SplFileObject::fputcsv + SplFileObject::setCsvControl + SplFileObject::getCsvControl + diff --git a/reference/spl/splfileobject/fgetcsv.xml b/reference/spl/splfileobject/fgetcsv.xml index 1ed35a0f932b..76e9f812dd60 100644 --- a/reference/spl/splfileobject/fgetcsv.xml +++ b/reference/spl/splfileobject/fgetcsv.xml @@ -1,6 +1,6 @@ - + SplFileObject::fgetcsv Gets line from file and parse as CSV fields @@ -17,13 +17,9 @@ Gets a line from the file which is in CSV format and returns an array containing the fields read. - - - The locale settings are taken into account by this function. If - LC_CTYPE is e.g. en_US.UTF-8, files in - one-byte encodings may be read wrongly by this function. - - + + + @@ -34,7 +30,9 @@ separator - The field delimiter (one single-byte character only). Defaults as a comma or the value set using SplFileObject::setCsvControl. + The field delimiter (one single-byte character only). + By default , or the value set by a prior call to + SplFileObject::setCsvControl. @@ -42,7 +40,9 @@ enclosure - The field enclosure character (one single-byte character only). Defaults as a double quotation mark or the value set using SplFileObject::setCsvControl. + The field enclosure character (one single-byte character only). + By default " or the value set by a prior call to + SplFileObject::setCsvControl. @@ -50,7 +50,10 @@ escape - The escape character (at most one single-byte character). Defaults as a backslash (\) or the value set using SplFileObject::setCsvControl. + The escape character (at most one single-byte character). + The field enclosure character (one single-byte character only). + By default \ or the value set by a prior call to + SplFileObject::setCsvControl. An empty string ("") disables the proprietary escape mechanism. @@ -65,6 +68,15 @@ even meant to escape itself. + + + As of PHP 8.4.0, depending on the default value of + escape is deprecated. + It needs to be provided explicitly either positionally or by the use + of Named Arguments, + or by a call to SplFileObject::setCsvControl. + + @@ -86,6 +98,10 @@ + + + + &reftitle.changelog; @@ -98,6 +114,9 @@ + + + 7.4.0 @@ -169,14 +188,17 @@ A salmon is a fish with 0 legs &reftitle.seealso; - - - SplFileObject::setCsvControl - SplFileObject::setFlags - SplFileObject::READ_CSV - SplFileObject::current - - + + SplFileObject::fputcsv + SplFileObject::setCsvControl + SplFileObject::getCsvControl + SplFileObject::setFlags + SplFileObject::READ_CSV + SplFileObject::current + fputcsv + fgetcsv + str_getcsv + diff --git a/reference/spl/splfileobject/fputcsv.xml b/reference/spl/splfileobject/fputcsv.xml index f6e4e8b8456a..aef7ef13d16b 100644 --- a/reference/spl/splfileobject/fputcsv.xml +++ b/reference/spl/splfileobject/fputcsv.xml @@ -1,6 +1,6 @@ - + SplFileObject::fputcsv Write a field array as a CSV line @@ -17,7 +17,8 @@ stringeol"\n" - Writes the fields array to the file as a CSV line. + Writes the fields array to the file + as a CSV line. @@ -32,34 +33,15 @@ - - separator - - - The optional separator parameter sets the field - delimiter (one single-byte character only). - - - - - enclosure - - - The optional enclosure parameter sets the field - enclosure (one single-byte character only). - - - - - escape - - - The optional escape parameter sets the - escape character (at most one single-byte character). - An empty string ("") disables the proprietary escape mechanism. - - - + + + + + + + + + eol @@ -85,21 +67,11 @@ Returns the length of the written string&return.falseforfailure;. - - Returns &false;, and does not write the CSV line to the file, if the - separator or enclosure - parameter is not a single character. - - - &reftitle.errors; - - An E_WARNING level error is issued if the - separator or enclosure - parameter is not a single character. - - + + + &reftitle.changelog; @@ -113,6 +85,9 @@ + + + 8.1.0 @@ -171,12 +146,14 @@ aaa,bbb,ccc,dddd &reftitle.seealso; - - - fputcsv - SplFileObject::fgetcsv - - + + SplFileObject::fgetcsv + SplFileObject::setCsvControl + SplFileObject::getCsvControl + fputcsv + fgetcsv + str_getcsv + diff --git a/reference/spl/splfileobject/getcsvcontrol.xml b/reference/spl/splfileobject/getcsvcontrol.xml index e4a7c334a3aa..bd2b1475b317 100644 --- a/reference/spl/splfileobject/getcsvcontrol.xml +++ b/reference/spl/splfileobject/getcsvcontrol.xml @@ -13,7 +13,8 @@ - Gets the delimiter, enclosure and escape character used for parsing CSV fields. + Gets the delimiter, enclosure and escape character used for + parsing CSV fields. @@ -89,14 +90,15 @@ Array &reftitle.seealso; - - - SplFileObject::setCsvControl - SplFileObject::fgetcsv - - + + SplFileObject::setCsvControl + SplFileObject::fgetcsv + SplFileObject::fputcsv + fputcsv + fgetcsv + str_getcsv + - - + SplFileObject::setCsvControl Set the delimiter, enclosure and escape character for CSV @@ -15,41 +15,24 @@ stringescape"\\" - Sets the delimiter, enclosure and escape character for parsing CSV fields. + Sets the delimiter, enclosure and escape character for + parsing CSV fields. &reftitle.parameters; - - - - separator - - - The field delimiter (one single-byte character only). - - - - - enclosure - - - The field enclosure character (one single-byte character only). - - - - - escape - - - The field escape character (at most one single-byte character). - An empty string ("") disables the proprietary escape mechanism. - - - - - + + + + + + + + + + + &warning.csv.escape-parameter; @@ -60,6 +43,10 @@ + + + + &reftitle.changelog; @@ -72,6 +59,9 @@ + + + 7.4.0 @@ -119,12 +109,14 @@ cherries|87 &reftitle.seealso; - - - SplFileObject::getCsvControl - SplFileObject::fgetcsv - - + + SplFileObject::getCsvControl + SplFileObject::fgetcsv + SplFileObject::fputcsv + fputcsv + fgetcsv + str_getcsv + diff --git a/reference/strings/functions/str-getcsv.xml b/reference/strings/functions/str-getcsv.xml index fd451082d4e8..b524d70f14f5 100644 --- a/reference/strings/functions/str-getcsv.xml +++ b/reference/strings/functions/str-getcsv.xml @@ -1,6 +1,6 @@ - + str_getcsv @@ -21,13 +21,9 @@ Parses a string input for fields in CSV format and returns an array containing the fields read. - - - The locale settings are taken into account by this function. If - LC_CTYPE is e.g. en_US.UTF-8, strings in - one-byte encodings may be read wrongly by this function. - - + + + @@ -42,44 +38,15 @@ - - separator - - - Set the field delimiter (one single-byte character only). - - - - - enclosure - - - Set the field enclosure character (one single-byte character only). - - - - - escape - - - Set the escape character (at most one single-byte character). Defaults as a backslash - (\) - An empty string ("") disables the proprietary escape mechanism. - - - - Usually an enclosure character is escaped inside - a field by doubling it; however, the escape - character can be used as an alternative. So for the default parameter - values "" and \" have the same - meaning. Other than allowing to escape the - enclosure character the - escape character has no special meaning; it isn't - even meant to escape itself. - - - - + + + + + + + + + &warning.csv.escape-parameter; @@ -92,6 +59,10 @@ + + + + &reftitle.changelog; @@ -104,6 +75,19 @@ + + + + + 8.4.0 + + Now throws a ValueError if + separator, enclosure, + or escape is invalid. + This mimics the behavior of fgetcsv and + fputcsv. + + 7.4.0 @@ -188,11 +172,14 @@ array(1) { &reftitle.seealso; - - - fgetcsv - - + + fputcsv + fgetcsv + SplFileObject::fgetcsv + SplFileObject::fputcsv + SplFileObject::setCsvControl + SplFileObject::getCsvControl +