str_getcsv()

La función str_getcsv() analiza una sola línea de texto CSV (valores separados por comas) y devuelve sus campos como un array plano. Es la contraparte en memoria de fgetcsv(): en lugar de leer una línea desde un manejador de archivo abierto, trabaja con una cadena que ya tienes — una fila pegada desde un formulario, una línea leída de una respuesta de API, o un elemento de un array que tú mismo dividiste.

Dado que el CSV real es más complicado de lo que parece (los campos pueden estar entre comillas, contener comas o abarcar el delimitador), str_getcsv() es casi siempre la opción correcta frente a un explode(',', $line) simple, que falla ante cualquier coma entrecomillada.

Sintaxis

str_getcsv(
    string $string,
    string $separator = ",",
    string $enclosure = "\"",
    string $escape = "\\"
): array

La función siempre devuelve un array. Un campo vacío se convierte en una cadena vacía (""); una línea de entrada completamente vacía devuelve [null].

Ejemplo básico

Salida:

Array
(
    [0] => John
    [1] => Doe
    [2] => 25
)

Cada valor separado por comas se convierte en un elemento, indexado desde 0.

Campos entrecomillados y comas incrustadas

Aquí es donde str_getcsv() demuestra su valor. Un campo entre comillas dobles puede contener el delimitador sin dividirse:

<?php
$input = '"Doe, John","New York, NY",25';
$array = str_getcsv($input);

print_r($array);
?>

Salida:

Array
(
    [0] => Doe, John
    [1] => New York, NY
    [2] => 25
)

Las comillas que envuelven el campo se eliminan, y las comas dentro de ellas se conservan como datos. explode(',', $input) habría producido incorrectamente cinco elementos aquí.

Usar un delimitador y un carácter de cierre distintos

Muchos archivos "CSV" están realmente separados por punto y coma o por tabulaciones. Sobrescribe el segundo y tercer argumento para adaptarte:

<?php
$input = "'Jane Doe';'Berlin';30";
$array = str_getcsv($input, ';', "'");

print_r($array);
?>

Salida:

Array
(
    [0] => Jane Doe
    [1] => Berlin
    [2] => 30
)

Para una línea separada por tabulaciones, usa "\t" como separador.

Analizar una cadena CSV multilínea

str_getcsv() analiza una línea a la vez. Para convertir un documento CSV completo en filas, divídelo primero en líneas y luego aplica la función a cada una. Combinarla con array_map() hace esto conciso:

<?php
$csv = "name,city,age\nJohn,Boston,25\nJane,Berlin,30";

$rows = array_map('str_getcsv', explode("\n", $csv));

print_r($rows);
?>

Salida:

Array
(
    [0] => Array
        (
            [0] => name
            [1] => city
            [2] => age
        )

    [1] => Array
        (
            [0] => John
            [1] => Boston
            [2] => 25
        )

    [2] => Array
        (
            [0] => Jane
            [1] => Berlin
            [2] => 30
        )

)

Nota: explode("\n", ...) es una división simple. Si tu archivo usa finales de línea de Windows (\r\n) o los campos contienen saltos de línea entre comillas, es preferible leer el archivo con fgetcsv() en un bucle, que gestiona esos casos de forma nativa.

Mapear filas a una cabecera

Un patrón habitual es usar la primera fila como claves y construir arrays asociativos con array_combine():

<?php
$lines  = ['name,city,age', 'John,Boston,25', 'Jane,Berlin,30'];
$header = str_getcsv(array_shift($lines));

$people = [];
foreach ($lines as $line) {
    $people[] = array_combine($header, str_getcsv($line));
}

print_r($people[0]);
?>

Salida:

Array
(
    [name] => John
    [city] => Boston
    [age] => 25
)

Errores comunes

• Una sola línea. Pasar una cadena multilínea trata todo como un único registro, así que siempre divide las líneas tú mismo antes de analizarlas.
• El carácter de escape sorprende a la gente. El escape por defecto \ de PHP no es estándar. Para datos que siguen RFC 4180 (donde " se escapa duplicándolo, como ""), pasa escape: "" para evitar que los barras invertidas sean consumidas.
• Los números siguen siendo cadenas. Cada campo se devuelve como string ("25", no 25). Convierte explícitamente cuando necesites números reales.
• Salto de línea al final. Una línea leída con un \n al final puede producir un último campo vacío; recorta la entrada antes si es necesario.

Funciones relacionadas

• fgetcsv() — leer y analizar una línea CSV directamente desde un manejador de archivo.
• fputcsv() — escribir un array en un archivo como línea CSV (la operación inversa).
• explode() — dividir una cadena por un delimitador cuando no hay campos entrecomillados de los que preocuparse.
• file_get_contents() — cargar un archivo CSV en una cadena para pasársela a str_getcsv().

Práctica