Descripción

fgetcsv(
    resource $stream,
    ?int $length = null,
    string $separator = ",",
    string $enclosure = "\"",
    string $escape = "\\"
): array|false

Similar a fgets() pero fgetcsv() analiza la línea que lee y busca los campos CSV, que devuelve en un array que los contiene.

Nota: 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 LC_CTYPE es en_US.UTF-8.

Parámetros

stream

Un puntero válido a un archivo abierto con fopen(), popen() o fsockopen().

length

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 length caracteres, a menos que la división ocurra dentro de un encierro.

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.

separator

El parámetro separator define el separador de campo. Debe tratarse de un carácter de un solo byte.

enclosure

El parámetro enclosure define el carácter de encierro de los campos. Debe tratarse de un carácter de un solo byte.

escape

El parámetro escape 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 ("") desactiva el mecanismo de escape propietario.

Advertencia

En el flujo de entrada, el carácter enclosure siempre puede ser escapado duplicándolo dentro de una cadena entrecomillada, lo que resulta en un único carácter enclosure en el resultado analizado. El carácter escape funciona de manera diferente: si una secuencia de caracteres escape y enclosure 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 "a""b","c\"d" tendrá los campos analizados como a"b y c\"d, respectivamente.

Advertencia

A partir de PHP 8.4.0, el uso del valor por omisión de escape está deprecado. Debe ser proporcionado explícitamente ya sea por posición o mediante el uso de los argumentos nombrados.

Advertencia

Cuando escape se define con un valor diferente a una cadena vacía (""), puede resultar en un CSV que no sea compatible con » RFC 4180 o que no pueda sobrevivir a un ciclo de ida y vuelta a través de las funciones CSV de PHP. El valor predeterminado de escape es "\\", por lo que se recomienda definirlo explícitamente como cadena vacía. El valor predeterminado cambiará en una futura versión de PHP, no antes de PHP 9.0.

Valores devueltos

Devuelve un array indexado que contiene los campos leídos en caso de éxito, o false si ocurre un error.

Nota:
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.

Nota: Si PHP no reconoce correctamente los finales de línea al leer archivos que han sido creados o leídos en un Macintosh, la activación de la opción de configuración auto_detect_line_endings puede resolver el problema.

Errores/Excepciones

Genera una ValueError si separator o enclosure no tiene una longitud de un byte.

Genera una ValueError si escape no tiene una longitud de un byte o es una cadena vacía.

Historial de cambios

Versión Descripción

8.4.0 Confiar en el valor por omisión de escape está ahora deprecado.

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

8.0.0 length ahora es nullable.

7.4.0 El parámetro escape ahora acepta una cadena vacía para desactivar el mecanismo de escape propietario.

Versión	Descripción
8.4.0	Confiar en el valor por omisión de `escape` está ahora deprecado.
8.3.0	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.
8.0.0	`length` ahora es nullable.
7.4.0	El parámetro `escape` ahora acepta una cadena vacía para desactivar el mecanismo de escape propietario.

Ejemplos

Ejemplo #1 Lee y muestra el contenido de un archivo CSV

<?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);
}
?>

Ver también

fputcsv() - Formatea una línea en CSV y la escribe en un fichero
str_getcsv() - Analiza una string CSV en un array
SplFileObject::fgetcsv() - Recupera una línea del archivo y la analiza como datos CSV
SplFileObject::fputcsv() - Escribe un array en forma de línea CSV
SplFileObject::setCsvControl() - Define las opciones CSV
SplFileObject::getCsvControl() - Recupera las opciones para CSV
explode() - Divide una string en segmentos
file() - Lee el fichero y devuelve el resultado en un array
pack() - Compacta datos en una cadena binaria