Skip to content

Commit

Permalink
PHP 8.4: CSV related changes and deprecations (php#4093)
Browse files Browse the repository at this point in the history 
Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>
  • Loading branch information
@Girgias @cmb69
Girgias and cmb69 authored Nov 19, 2024
1 parent 35ca7f1 commit 73007ad
Show file tree
Hide file tree
Showing 7 changed files with 217 additions and 219 deletions.
59 changes: 45 additions & 14 deletions reference/filesystem/functions/fgetcsv.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,11 +23,12 @@
read.
</para>
<note>
<para>
The locale settings are taken into account by this function. If
<constant>LC_CTYPE</constant> is e.g. <literal>en_US.UTF-8</literal>, files in
one-byte encodings may be read wrongly by this function.
</para>
<simpara>
The locale settings are taken into account by this function.
For example, data encoded in certain one-byte encodings may be parsed
incorrectly if <constant>LC_CTYPE</constant> is
<literal>en_US.UTF-8</literal>.
</simpara>
</note>
</refsect1>

Expand Down Expand Up @@ -96,6 +97,14 @@
even meant to escape itself.
</simpara>
</note>
<warning>
<simpara>
As of PHP 8.4.0, depending on the default value of
<parameter>escape</parameter> is deprecated.
It needs to be provided explicitly either positionally or by the use
of <link linkend="functions.named-arguments">named arguments</link>.
</simpara>
</warning>
</listitem>
</varlistentry>
</variablelist>
Expand All @@ -118,6 +127,19 @@
&note.line-endings;
</refsect1>

<refsect1 role="errors">
&reftitle.errors;
<simpara>
Throws a <exceptionname>ValueError</exceptionname> if
<parameter>separator</parameter> or <parameter>enclosure</parameter>
is not one byte long.
</simpara>
<simpara>
Throws a <exceptionname>ValueError</exceptionname> if
<parameter>escape</parameter> is not one byte long or the empty string.
</simpara>
</refsect1>

<refsect1 role="changelog">
&reftitle.changelog;
<para>
Expand All @@ -130,6 +152,13 @@
</row>
</thead>
<tbody>
<row>
<entry>8.4.0</entry>
<entry>
Relying on the default value of <parameter>escape</parameter> is now
deprecated.
</entry>
</row>
<row>
<entry>8.0.0</entry>
<entry>
Expand Down Expand Up @@ -178,15 +207,17 @@ if (($handle = fopen("test.csv", "r")) !== FALSE) {

<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>str_getcsv</function></member>
<member><function>explode</function></member>
<member><function>file</function></member>
<member><function>pack</function></member>
<member><function>fputcsv</function></member>
</simplelist>
</para>
<simplelist>
<member><function>fputcsv</function></member>
<member><function>str_getcsv</function></member>
<member><methodname>SplFileObject::fgetcsv</methodname></member>
<member><methodname>SplFileObject::fputcsv</methodname></member>
<member><methodname>SplFileObject::setCsvControl</methodname></member>
<member><methodname>SplFileObject::getCsvControl</methodname></member>
<member><function>explode</function></member>
<member><function>file</function></member>
<member><function>pack</function></member>
</simplelist>
</refsect1>

</refentry>
Expand Down
69 changes: 28 additions & 41 deletions reference/filesystem/functions/fputcsv.xml
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.fputcsv" xmlns="http://docbook.org/ns/docbook">
<refentry xml:id="function.fputcsv" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
<refnamediv>
<refname>fputcsv</refname>
<refpurpose>Format line as CSV and write to file pointer</refpurpose>
Expand All @@ -19,8 +19,9 @@
</methodsynopsis>
<para>
<function>fputcsv</function> formats a line (passed as a
<parameter>fields</parameter> array) as CSV and writes it (terminated by a
newline) to the specified file <parameter>stream</parameter>.
<parameter>fields</parameter> array) as <acronym>CSV</acronym> and writes it
(terminated by a <parameter>eol</parameter>) to the specified
<parameter>stream</parameter>.
</para>
</refsect1>

Expand All @@ -42,34 +43,15 @@
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>separator</parameter></term>
<listitem>
<para>
The optional <parameter>separator</parameter> parameter sets the field
delimiter (one single-byte character only).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>enclosure</parameter></term>
<listitem>
<para>
The optional <parameter>enclosure</parameter> parameter sets the field
enclosure (one single-byte character only).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>escape</parameter></term>
<listitem>
<para>
The optional <parameter>escape</parameter> parameter sets the
escape character (at most one single-byte character).
An empty string (<literal>""</literal>) disables the proprietary escape mechanism.
</para>
</listitem>
</varlistentry>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.fgetcsv')/db:refsect1[@role='parameters']//db:varlistentry[db:term[db:parameter[text()='separator']]]/.)">
<xi:fallback/>
</xi:include>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.fgetcsv')/db:refsect1[@role='parameters']//db:varlistentry[db:term[db:parameter[text()='enclosure']]]/.)">
<xi:fallback/>
</xi:include>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.fgetcsv')/db:refsect1[@role='parameters']//db:varlistentry[db:term[db:parameter[text()='escape']]]/.)">
<xi:fallback/>
</xi:include>
<varlistentry>
<term><parameter>eol</parameter></term>
<listitem>
Expand Down Expand Up @@ -98,6 +80,10 @@
</para>
</refsect1>

<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.fgetcsv')/db:refsect1[@role='errors']/.)">
<xi:fallback/>
</xi:include>

<refsect1 role="changelog">
&reftitle.changelog;
<para>
Expand All @@ -110,6 +96,9 @@
</row>
</thead>
<tbody>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.fgetcsv')/db:refsect1[@role='changelog']//db:row[db:entry[text()='8.4.0']]/.)">
<xi:fallback/>
</xi:include>
<row>
<entry>8.1.0</entry>
<entry>
Expand Down Expand Up @@ -167,18 +156,16 @@ aaa,bbb,ccc,dddd
</para>
</refsect1>

<refsect1 role="notes">
&reftitle.notes;
&note.line-endings;
</refsect1>

<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>fgetcsv</function></member>
</simplelist>
</para>
<simplelist>
<member><function>fgetcsv</function></member>
<member><function>str_getcsv</function></member>
<member><methodname>SplFileObject::fgetcsv</methodname></member>
<member><methodname>SplFileObject::fputcsv</methodname></member>
<member><methodname>SplFileObject::setCsvControl</methodname></member>
<member><methodname>SplFileObject::getCsvControl</methodname></member>
</simplelist>
</refsect1>

</refentry>
Expand Down
60 changes: 41 additions & 19 deletions reference/spl/splfileobject/fgetcsv.xml
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="splfileobject.fgetcsv" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refentry xml:id="splfileobject.fgetcsv" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
<refnamediv>
<refname>SplFileObject::fgetcsv</refname>
<refpurpose>Gets line from file and parse as CSV fields</refpurpose>
Expand All @@ -17,13 +17,9 @@
<para>
Gets a line from the file which is in <acronym>CSV</acronym> format and returns an array containing the fields read.
</para>
<note>
<para>
The locale settings are taken into account by this function. If
<constant>LC_CTYPE</constant> is e.g. <literal>en_US.UTF-8</literal>, files in
one-byte encodings may be read wrongly by this function.
</para>
</note>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.fgetcsv')/db:refsect1[@role='description']//db:note/.)">
<xi:fallback/>
</xi:include>
</refsect1>

<refsect1 role="parameters">
Expand All @@ -34,23 +30,30 @@
<term><parameter>separator</parameter></term>
<listitem>
<para>
The field delimiter (one single-byte character only). Defaults as a comma or the value set using <methodname>SplFileObject::setCsvControl</methodname>.
The field delimiter (one single-byte character only).
By default <literal>,</literal> or the value set by a prior call to
<methodname>SplFileObject::setCsvControl</methodname>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>enclosure</parameter></term>
<listitem>
<para>
The field enclosure character (one single-byte character only). Defaults as a double quotation mark or the value set using <methodname>SplFileObject::setCsvControl</methodname>.
The field enclosure character (one single-byte character only).
By default <literal>"</literal> or the value set by a prior call to
<methodname>SplFileObject::setCsvControl</methodname>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>escape</parameter></term>
<listitem>
<para>
The escape character (at most one single-byte character). Defaults as a backslash (<literal>\</literal>) or the value set using <methodname>SplFileObject::setCsvControl</methodname>.
The escape character (at most one single-byte character).
The field enclosure character (one single-byte character only).
By default <literal>\</literal> or the value set by a prior call to
<methodname>SplFileObject::setCsvControl</methodname>.
An empty string (<literal>""</literal>) disables the proprietary escape mechanism.
</para>
<note>
Expand All @@ -65,6 +68,15 @@
even meant to escape itself.
</simpara>
</note>
<warning>
<simpara>
As of PHP 8.4.0, depending on the default value of
<parameter>escape</parameter> is deprecated.
It needs to be provided explicitly either positionally or by the use
of <link linkend="functions.named-arguments">Named Arguments</link>,
or by a call to <methodname>SplFileObject::setCsvControl</methodname>.
</simpara>
</warning>
</listitem>
</varlistentry>
</variablelist>
Expand All @@ -86,6 +98,10 @@
</note>
</refsect1>

<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.fgetcsv')/db:refsect1[@role='errors']/.)">
<xi:fallback/>
</xi:include>

<refsect1 role="changelog">
&reftitle.changelog;
<para>
Expand All @@ -98,6 +114,9 @@
</row>
</thead>
<tbody>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.fgetcsv')/db:refsect1[@role='changelog']//db:row[db:entry[text()='8.4.0']]/.)">
<xi:fallback/>
</xi:include>
<row>
<entry>7.4.0</entry>
<entry>
Expand Down Expand Up @@ -169,14 +188,17 @@ A salmon is a fish with 0 legs

<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><methodname>SplFileObject::setCsvControl</methodname></member>
<member><methodname>SplFileObject::setFlags</methodname></member>
<member><link linkend="splfileobject.constants.read-csv">SplFileObject::READ_CSV</link></member>
<member><methodname>SplFileObject::current</methodname></member>
</simplelist>
</para>
<simplelist>
<member><methodname>SplFileObject::fputcsv</methodname></member>
<member><methodname>SplFileObject::setCsvControl</methodname></member>
<member><methodname>SplFileObject::getCsvControl</methodname></member>
<member><methodname>SplFileObject::setFlags</methodname></member>
<member><constant>SplFileObject::READ_CSV</constant></member>
<member><methodname>SplFileObject::current</methodname></member>
<member><function>fputcsv</function></member>
<member><function>fgetcsv</function></member>
<member><function>str_getcsv</function></member>
</simplelist>
</refsect1>

</refentry>
Expand Down
Loading

0 comments on commit 73007ad

Please sign in to comment.