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

<!-- EN-Revision: 0a3648a71895f35f570573d31ca9e003786aa993 Maintainer: PhilDaiguille Status: ready -->

<!-- Reviewed: no -->

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

<refnamediv>

<refname>fgetcsv</refname>

<refpurpose>Obtiene una línea desde un puntero de archivo y la analiza para campos 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>

Similar a <function>fgets</function> pero <function>fgetcsv</function>

analiza la línea que lee y busca los campos <acronym>CSV</acronym>,

que devuelve en un array que los contiene.

</para>

<note>

<simpara>

Los parámetros de configuración local son tenidos en cuenta por esta función.

Por ejemplo, los datos codificados en ciertos juegos de caracteres de un byte pueden ser analizados

incorrectamente si <constant>LC_CTYPE</constant> es

<literal>en_US.UTF-8</literal>.

</simpara>

</note>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

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

<listitem>

<para>

Un puntero válido a un archivo abierto con <function>fopen</function>,

<function>popen</function> o <function>fsockopen</function>.

</para>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem>

<para>

Debe ser mayor que la línea más larga (en términos de caracteres)

a leer en el archivo (incluyendo el carácter de fin de línea).

En caso contrario la línea será dividida en fragmentos de <parameter>length</parameter> caracteres,

a menos que la división ocurra dentro de un encierro.

</para>

<para>

Omitir este parámetro (o establecerlo a 0, o &null; en PHP 8.0.0 o

versiones posteriores) hace que la longitud máxima de la línea no esté limitada,

lo cual es ligeramente más lento.

</para>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem>

<para>

El parámetro <parameter>separator</parameter> define el separador de campo.

Debe tratarse de un carácter de un solo byte.

</para>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem>

<para>

El parámetro <parameter>enclosure</parameter> define el carácter de encierro de los campos.

Debe tratarse de un carácter de un solo byte.

</para>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem>

<para>

El parámetro <parameter>escape</parameter> define el carácter de escape.

Debe tratarse de un carácter de un solo byte o una cadena vacía.

La cadena vacía (<literal>""</literal>) desactiva el mecanismo de escape propietario.

</para>

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

<simpara>

En el flujo de entrada, el carácter <parameter>enclosure</parameter>

siempre puede ser escapado duplicándolo dentro de una cadena entrecomillada,

lo que resulta en un único carácter <parameter>enclosure</parameter>

en el resultado analizado.

El carácter <parameter>escape</parameter> funciona de manera diferente:

si una secuencia de caracteres <parameter>escape</parameter> y

<parameter>enclosure</parameter> aparece en la entrada,

ambos caracteres estarán presentes en el resultado analizado.

Así, para los parámetros por defecto, una línea CSV como

<literal>"a""b","c\"d"</literal> tendrá los campos analizados como

<literal>a"b</literal> y <literal>c\"d</literal>, respectivamente.

</simpara>

</warning>

<warning>

<simpara>

A partir de PHP 8.4.0, el uso del valor por omisión de

<parameter>escape</parameter> está deprecado.

Debe ser proporcionado explícitamente ya sea por posición o mediante el uso

de los <link linkend="functions.named-arguments">argumentos nombrados</link>.

</simpara>

</warning>

</listitem>

</varlistentry>

</variablelist>

</para>

&warning.csv.escape-parameter;

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Devuelve un array indexado que contiene los campos leídos en caso de éxito, &return.falseforfailure;.

</para>

<note>

<para>

Una línea vacía en un archivo CSV será devuelta

en forma de un array que contiene el valor &null; y no será tratada

como un error.

</para>

</note>

&note.line-endings;

</refsect1>

<refsect1 role="errors">

&reftitle.errors;

<simpara>

Genera una <exceptionname>ValueError</exceptionname> si

<parameter>separator</parameter> o <parameter>enclosure</parameter>

no tiene una longitud de un byte.

</simpara>

<simpara>

Genera una <exceptionname>ValueError</exceptionname> si

<parameter>escape</parameter> no tiene una longitud de un byte o es una cadena vacía.

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

Confiar en el valor por omisión de <parameter>escape</parameter> está ahora

deprecado.

</entry>

</row>

<row>

<entry>8.3.0</entry>

<entry>

Una cadena vacía es devuelta en lugar de una cadena que contiene un solo

byte nulo para el último campo si este contiene únicamente un delimitador no terminado.

</entry>

</row>

<row>

<entry>8.0.0</entry>

<entry>

<parameter>length</parameter> ahora es nullable.

</entry>

</row>

<row>

<entry>7.4.0</entry>

<entry>

El parámetro <parameter>escape</parameter> ahora acepta una cadena vacía

para desactivar el mecanismo de escape propietario.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>Lee y muestra el contenido de un archivo 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 campos en la línea $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

-->