Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

PHP 8.4: CSV related changes and deprecations #4093

Merged
merged 4 commits into from
Nov 19, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 45 additions & 14 deletions reference/filesystem/functions/fgetcsv.xml
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
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
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