str_getcsv()

A função str_getcsv() analisa uma única linha de texto CSV (valores separados por vírgula) e retorna seus campos como um array simples. Ela é a contraparte em memória de fgetcsv(): em vez de ler uma linha de um identificador de arquivo aberto, opera sobre uma string que você já possui — uma linha colada de um formulário, uma única linha lida de uma resposta de API, ou um elemento de um array que você mesmo dividiu.

Como CSV real é mais difícil do que parece (campos podem estar entre aspas, conter vírgulas ou abranger o delimitador), str_getcsv() é quase sempre a escolha certa em vez de um simples explode(',', $line), que quebra em qualquer vírgula entre aspas.

Sintaxe

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

A função sempre retorna um array. Um campo vazio torna-se uma string vazia (""); uma linha de entrada completamente vazia retorna [null].

Exemplo básico

Saída:

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

Cada valor separado por vírgula torna-se um elemento, indexado a partir de 0.

Campos entre aspas e vírgulas incorporadas

É aqui que str_getcsv() mostra seu valor. Um campo entre aspas duplas pode conter o delimitador sem dividir:

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

print_r($array);
?>

Saída:

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

As aspas delimitadoras são removidas, e as vírgulas dentro delas são mantidas como dados. explode(',', $input) teria produzido incorretamente cinco elementos aqui.

Usando um delimitador e delimitador de campo diferentes

Muitos arquivos "CSV" são na verdade separados por ponto e vírgula ou tabulação. Substitua o segundo e terceiro argumentos para corresponder:

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

print_r($array);
?>

Saída:

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

Para uma linha separada por tabulação, use "\t" como separador.

Analisando uma string CSV multilinha

str_getcsv() analisa uma linha por vez. Para transformar um documento CSV completo em linhas, divida-o em linhas primeiro e depois aplique a função em cada linha. Combiná-la com array_map() mantém isso conciso:

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

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

print_r($rows);
?>

Saída:

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", ...) é uma divisão simples. Se o seu arquivo usa terminações de linha do Windows (\r\n) ou campos contêm quebras de linha entre aspas, prefira ler o arquivo com fgetcsv() em um loop, que lida com esses casos nativamente.

Mapeando linhas para um cabeçalho

Um padrão comum é usar a primeira linha como chaves e construir arrays associativos com 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]);
?>

Saída:

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

Armadilhas comuns

• Apenas uma linha. Passar uma string multilinha trata tudo como um único registro, então sempre divida em linhas antes de analisar.
• O caractere de escape surpreende as pessoas. O escape padrão \ do PHP não é padrão. Para dados que seguem o RFC 4180 (onde " é escapado por duplicação, como ""), passe escape: "" para evitar que as barras invertidas sejam consumidas.
• Números permanecem como strings. Cada campo retorna como string ("25", não 25). Faça a conversão explicitamente quando precisar de números reais.
• Quebra de linha ao final. Uma linha lida com \n ao final pode produzir um último campo vazio; remova o espaço em branco do início/fim da entrada, se necessário.

Funções relacionadas

• fgetcsv() — lê e analisa uma linha CSV diretamente de um identificador de arquivo.
• fputcsv() — escreve um array em um arquivo como uma linha CSV (o inverso).
• explode() — divide uma string por um delimitador quando não há campos entre aspas para se preocupar.
• file_get_contents() — carrega um arquivo CSV em uma string para alimentar str_getcsv().

Prática