<?xml version="1.0" encoding="utf-8"?>

<!-- $Revision$ -->

<refentry xml:id="function.fgetcsv" xmlns="http://docbook.org/ns/docbook">

<refnamediv>

<refname>fgetcsv</refname>

<refpurpose>Gets line from file pointer and parse for CSV fields</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type class="union"><type>array</type><type>false</type></type><methodname>fgetcsv</methodname>

<methodparam><type>resource</type><parameter>stream</parameter></methodparam>

<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>length</parameter><initializer>&null;</initializer></methodparam>

<methodparam choice="opt"><type>string</type><parameter>separator</parameter><initializer>","</initializer></methodparam>

<methodparam choice="opt"><type>string</type><parameter>enclosure</parameter><initializer>"\""</initializer></methodparam>

<methodparam choice="opt"><type>string</type><parameter>escape</parameter><initializer>"\\"</initializer></methodparam>

</methodsynopsis>

<para>

Similar to <function>fgets</function> except that

<function>fgetcsv</function> parses the line it reads for fields in

<acronym>CSV</acronym> format and returns an array containing the fields

read.

</para>

<note>

<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>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>stream</parameter></term>

<listitem>

<para>

A valid file pointer to a file successfully opened by

<function>fopen</function>, <function>popen</function>, or

<function>fsockopen</function>.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>length</parameter></term>

<listitem>

<para>

Must be greater than the longest line (in characters) to be found in

the CSV file (allowing for trailing line-end characters). Otherwise the

line is split in chunks of <parameter>length</parameter> characters,

unless the split would occur inside an enclosure.

</para>

<para>

Omitting this parameter (or setting it to 0,

or &null; in PHP 8.0.0 or later) the maximum line length is not limited,

which is slightly slower.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>separator</parameter></term>

<listitem>

<para>

The <parameter>separator</parameter> parameter sets the field separator.

It must be a single byte character.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>enclosure</parameter></term>

<listitem>

<para>

The <parameter>enclosure</parameter> parameter sets the field enclosure character.

It must be a single byte character.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>escape</parameter></term>

<listitem>

<para>

The <parameter>escape</parameter> parameter sets the escape character.

It must be a single byte character or the empty string.

The empty string (<literal>""</literal>) disables the proprietary escape mechanism.

</para>

<warning xml:id="function.fgetcsv..warn.escape.parameter">

<simpara>

In the input stream, the <parameter>enclosure</parameter> character

can always be escaped by doubling it inside a quoted string,

resulting in a single <parameter>enclosure</parameter> character

in the parsed result.

The <parameter>escape</parameter> character works differently:

If a sequence of <parameter>escape</parameter> and

<parameter>enclosure</parameter> characters appear in the input,

both characters will be present in the parsed result.

So for the default parameters, a CSV line like

<literal>"a""b","c\"d"</literal> will have the fields parsed as

<literal>a"b</literal> and <literal>c\"d</literal>, respectively.

</simpara>

</warning>

<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>

</para>

&warning.csv.escape-parameter;

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Returns an indexed array containing the fields read on success, &return.falseforfailure;.

</para>

<note>

<para>

A blank line in a CSV file will be returned as an array

comprising a single <type>null</type> field, and will not be treated

as an error.

</para>

</note>

&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>

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</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.3.0</entry>

<entry>

An empty string is returned instead of a string with a single

null byte for the last field if it contains only an unterminated

enclosure.

</entry>

</row>

<row>

<entry>8.0.0</entry>

<entry>

<parameter>length</parameter> is now nullable.

</entry>

</row>

<row>

<entry>7.4.0</entry>

<entry>

The <parameter>escape</parameter> parameter now also accepts an empty

string to disable the proprietary escape mechanism.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>Read and print the entire contents of a CSV file</title>

<programlisting role="php">

<![CDATA[

<?php

$row = 1;

if (($handle = fopen("test.csv", "r")) !== FALSE) {

while (($data = fgetcsv($handle, 1000, ",")) !== FALSE) {

$num = count($data);

echo "<p> $num fields in line $row: <br /></p>\n";

$row++;

for ($c=0; $c < $num; $c++) {

echo $data[$c] . "<br />\n";

}

}

fclose($handle);

}

?>

]]>

</programlisting>

</example>

</para>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<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>

<!-- Keep this comment at the end of the file

Local variables:

mode: sgml

sgml-omittag:t

sgml-shorttag:t

sgml-minimize-attributes:nil

sgml-always-quote-attributes:t

sgml-indent-step:1

sgml-indent-data:t

indent-tabs-mode:nil

sgml-parent-document:nil

sgml-default-dtd-file:"~/.phpdoc/manual.ced"

sgml-exposed-tags:nil

sgml-local-catalogs:nil

sgml-local-ecat-files:nil

End:

vim600: syn=xml fen fdm=syntax fdl=2 si

vim: et tw=78 syn=sgml

vi: ts=1 sw=1

-->