fgetcsv.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 781f2ec04ee8817687e5e333bc3e64ab973322d7 Maintainer: adi Status: ready -->
<!-- CREDITS: sobak, grzesiek -->
<refentry xml:id="function.fgetcsv" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>fgetcsv</refname>
  <refpurpose>Pobiera linię ze wskanika pliku i przetwarza na pola 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>
   Działa podobnie do <function>fgets</function> tylko, że
   <function>fgetcsv</function> przetwarza odczytaną linię na pola
   w formacie <acronym>CSV</acronym> i zwraca tablicę zawierającą
   odczytane pola.
  </para>
  <note>
   <para>
    Ta funkcja bierze pod uwagę ustawienia regionalne.
    Przykładowo dane zakodowane niektórymi kodowaniami jednobajtowymi mogą nie być
    parsowane poprawnie, jeśli stała <constant>LC_CTYPE</constant> ma 
    wartość <literal>en_US.UTF-8</literal>.
   </para>
  </note>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>stream</parameter></term>
      <listitem>
       <para>
        Ważny uchwyt pliku, poprawnie otwartego za pomocą
        <function>fopen</function>, <function>popen</function> lub
        <function>fsockopen</function>.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>length</parameter></term>
       <listitem>
        <para>
         Musi być większy niż najdłuższa linia (w znakach), która znajduje się w
         pliku CSV (wliczając znaki końca lini). W przeciwnym wypadku linia
         jest dzielona na kawałki o podanej <parameter>length</parameter>i,
         chyba że linia miałaby być podzielona wewnątrz ogranicznika.
        </para>
        <para>
         Pominięcie tego parametru (lub ustawienie go na 0 lub &null; w PHP
         8.0.0 lub późniejszym) spowoduje, że maksymalna długość lini nie jest limitowana,
         co jest nieznacznie wolniejsze.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term><parameter>separator</parameter></term>
       <listitem>
        <para>
         Opcjonalny parametr <parameter>separator</parameter> ustawia separator pola
         (tylko jeden znak jednobajtowy).
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term><parameter>enclosure</parameter></term>
       <listitem>
        <para>
         Parametr <parameter>enclosure</parameter> ustawia znak okalający pojedyncze pole.
         Musi być znakiem jednobajtowym.
        </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>escape</parameter></term>
     <listitem>
      <para>
       Parametr <parameter>escape</parameter> ustawia znak ucieczki (escape'owania).
       Musi być znakiem jednobajtowym lub pustym ciągiem znaków.
       Pusty ciąg znaków (<literal>""</literal>) wyłącza własnościowy mechanizm ucieczki.
      </para>
      <warning xml:id="function.fgetcsv..warn.escape.parameter">
       <simpara>
        W strumieniu wejściowym znak <parameter>enclosure</parameter>
        zawsze może być unikany przez podwojenie wewnątrz cytowanego ciągu,
        co daje pojedynczy znak <parameter>enclosure</parameter>
        w przetworzonym wyniku.
        Znak <parameter>escape</parameter> działa inaczej:
        jeśli sekwencja znaków <parameter>escape</parameter> i
        <parameter>enclosure</parameter> pojawia się na wejściu,
        oba znaki będą obecne w przetworzonym wyniku.
        Tak więc dla domyślnych parametrów, linia CSV taka jak
        <literal>"a""b","c\"d"</literal> będzie miała pola przetworzone jako
        <literal>a"b</literal> i <literal>c\"d</literal>.
       </simpara>
      </warning>
      <warning>
       <simpara>
        Począwszy od PHP 8.4.0 poleganie na domyślnej wartości
        parametru <parameter>escape</parameter> jest przestarzałe.
        Musi on zostać jawnie ustawiony, pozycyjnie lub używając
        <link linkend="functions.named-arguments">nazwanych argumentów</link>.
       </simpara>
      </warning>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
  &warning.csv.escape-parameter;
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Zwraca indeksowaną tablicę zawierającą odczytane pola w przypadku powodzenia&return.falseforfailure;.
  </para>
  <note>
   <para>
    Pusta linia w pliku CSV zostanie zwrócona jako tablica
    składająca się z pojedynczego pola <type>null</type> i nie zostanie potraktowana
    jako błąd.
   </para>
  </note>
  &note.line-endings;
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <simpara>
   Rzuca <exceptionname>ValueError</exceptionname> jeśli parametry
   <parameter>separator</parameter> lub <parameter>enclosure</parameter>
   nie mają długości jednego bajtu.
  </simpara>
  <simpara>
   Rzuca <exceptionname>ValueError</exceptionname> jeśli parametr
   <parameter>escape</parameter> nie ma długości jednego bajtu lub jest pustym ciągiem znaków.
  </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>
        Poleganie na domyślnej wartości parametru <parameter>escape</parameter> jest
        teraz przestarzałe.
       </entry>
      </row>
      <row>
       <entry>8.3.0</entry>
       <entry>
        Jeśli ostatnie pole zawiera niezakończony znak zamknięcia,
        to zwracany jest teraz pusty ciąg znaków, a nie ciąg z pojedynczym
        bajtem null.
       </entry>
      </row>
      <row>
       <entry>8.0.0</entry>
       <entry>
        Parametr <parameter>length</parameter> dopuszcza teraz &null;.
       </entry>
      </row>
      <row>
       <entry>7.4.0</entry>
       <entry>
       Parametr <parameter>escape</parameter> dopuszcza teraz również pusty
       ciąg znaków, aby wyłączyć zastrzeżony mechanizm ucieczki.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>
     <function>fgetcsv</function> przykład - Odczyt i wyświetlenie całej
     zawartości pliku 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
-->