fgetcsv.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 781f2ec04ee8817687e5e333bc3e64ab973322d7 Maintainer: HonestQiao Status: ready -->
<!-- CREDITS: mowangjuanzi, Luffy -->
<refentry xml:id="function.fgetcsv" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>fgetcsv</refname>
  <refpurpose>从文件指针中读入一行并解析 CSV 字段</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>
   和 <function>fgets</function> 类似，只除了
   <function>fgetcsv</function> 解析读入的行并找出 <acronym>CSV</acronym>
   格式的字段然后返回一个包含这些字段的数组。
  </para>
  <note>
   <para>
    此函数会考虑区域设置。例如，如果 <constant>LC_CTYPE</constant> 为
    <literal>en_US.UTF-8</literal>，可能会错误的解析某些单字节编码的数据。
   </para>
  </note>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>stream</parameter></term>
     <listitem>
      <para>
       一个由 <function>fopen</function>、<function>popen</function> 或
       <function>fsockopen</function> 产生的有效文件指针。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>length</parameter></term>
     <listitem>
      <para>
       必须大于在 CVS 文件（允许尾随行尾字符）中找到的最长行（以字符为单位）。否则，该行将拆分为
       <parameter>length</parameter> 字符的块，除非拆分发生在环绕字符内。
      </para>
      <para>
       忽略此参数（或者设为 0 或者在 PHP 8.0.0 及以后的版本中设为 &null;）行的最大长度将不受限制，速度稍慢。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>separator</parameter></term>
     <listitem>
      <para>
       可选的 <parameter>separator</parameter> 参数，设置字段分隔符。必须是单字节字符。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>enclosure</parameter></term>
     <listitem>
      <para>
       可选的 <parameter>enclosure</parameter> 参数，设置字段环绕符。必须是单字节字符。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>escape</parameter></term>
     <listitem>
      <para>
       可选的 <parameter>escape</parameter>
       参数，设置转义字符。必须是单字节字符或者空字符串。空字符串（<literal>""</literal>）禁用所有的转义机制。
      </para>
      <note>
       <simpara>
        通常，在字段内，通过双倍的 <parameter>enclosure</parameter> 字符对其进行转义；但是可以使用
        <parameter>escape</parameter> 字符作为替代。因此，对于默认参数值，<literal>""</literal> 和
        <literal>\"</literal> 具有相同的含义。除了允许转义 <parameter>enclosure</parameter>
        字符外，<parameter>escape</parameter> 字符没有特殊含义；甚至不打算转义自身。
       </simpara>
      </note>
      <warning>
       <simpara>
        从 PHP 8.4.0 开始，弃用依赖 <parameter>escape</parameter> 的默认值。需要通过位置或使用<link
        linkend="functions.named-arguments">命名参数</link>明确提供。
       </simpara>
      </warning>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
  &warning.csv.escape-parameter;
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   成功时返回包含读取字段的索引数组，&return.falseforfailure;。
  </para>
  <note>
   <para>    
    CSV 文件中的空行将被返回为一个包含有单个 <type>null</type> 字段的数组，不会被当成错误。
   </para>
  </note>
  &note.line-endings;
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <simpara>
   如果 <parameter>separator</parameter> 或者 <parameter>enclosure</parameter>
   长度不是一个字节，则抛出 <exceptionname>ValueError</exceptionname>。
  </simpara>
  <simpara>
   如果 <parameter>escape</parameter> 的长度不是一个字节或者为空字符串，则抛出 <exceptionname>ValueError</exceptionname>。
  </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>
        现在已弃用依赖 escape 的默认值。
       </entry>
      </row>
      <row>
       <entry>8.3.0</entry>
       <entry>
        如果最后一个字段仅包含未终止的 enclosure，则返回空字符串，而不是带有单个 NULL 字节的字符串。
       </entry>
      </row>
      <row>
       <entry>8.0.0</entry>
       <entry>
        现在 <parameter>length</parameter> 允许为 null.
       </entry>
      </row>
      <row>
       <entry>7.4.0</entry>
       <entry>
        <parameter>escape</parameter> 参数也接受空字符串来禁用所有的转义机制。
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>读取并显示 CSV 文件的整个内容</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
-->