fgetcsv

(PHP 4, PHP 5, PHP 7, PHP 8)

fgetcsvLê uma linha do ponteiro de arquivos e a interpreta como campos CSV

Descrição

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

Similar à função fgets(), exceto que a fgetcsv() interpreta a linha em busca de campos no formato CSV e retorna um array contendo os campos lidos.

Nota: As configurações de localidade são consideradas por esta função. Por exemplo, dados em certas codificações de um byte podem ser interpretados incorretamente se LC_CTYPE for en_US.UTF-8.

Parâmetros

stream

Um ponteiro de arquivo válido para um arquivo aberto com sucesso por fopen(), popen() ou fsockopen().

length

Deve ser maior do que a maior linha (em caracteres) a ser encontrada no arquivo CSV (considerando também os caracteres de fim-de-linha). Caso contrário a linha é dividida em partes de length caracteres, a não ser que a divisão ocorra dentro de um caractere que cerca os campos (enclosure).

Se este parâmetro for omitido (ou definido em 0 ou null a partir do PHP 8.0.0), o tamanho máximo das linhas não é limitado, o que é um pouco mais lento.

separator

O parâmetro separator define o delimitador de campo. Precisa ser um caractere de um byte.

enclosure

O parâmetro enclosure define o caractere que cerca um campo. Precisa ser um caractere de um byte.

escape

O parâmetro escape define o caractere de escape. Precisa ser um caractere de um byte ou uma string vazia. Uma string vazia ("") desabilita o mecanismo de escape proprietário.

Nota: Normalmente um caractere de enclosure sofre escape dentro de um campo através da duplicação; entretanto, o caractere escape pode ser usado como uma alternativa. Portanto, para os parâmetros padrões os valores "" e \" têm o mesmo significado. Além de permitir fazer escape no caractere enclosure, o caractere escape não tem nenhum significado especial adicional; muito menos foi projetado para fazer escape de si mesmo.

Aviso

A partir do PHP 8.4.0, depender do valor padrão de escape foi descontinuado. Ele precisa ser fornecido explicitamente tanto por posição quanto pelo uso de argumentos nomeados.

Aviso

Quando o parâmetro escape for definido para algo diferente de uma string vazia (""), isso pode resultar em um CSV que não esteja conforme a » RFC 4180 ou que não seja capaz de sobreviver a uma viagem de ida e volta através das funções CSV do PHP. O padrão para escape é "\\", portanto é recomendado defini-lo explicitamente para a string vazia. O valor padrão será alterado em uma versão futura do PHP, mas não antes do PHP 9.0.

Valor Retornado

Retorna um array indexado contendo os campos lidos em caso de sucesso, ou false em caso de falha.

Nota:

Uma linha em branco em um arquivo CSV será retornada como um array contendo um único campo nulo (null) e não será tratada como um erro.

Nota: Se o PHP não estiver reconhecendo corretamente os finais de linha ao ler arquivos em um computador Macintosh ou que foram criados em um, habilitar a opção de configuração em tempo de execução auto_detect_line_endings pode ajudar a resolver o problema.

Erros/Exceções

Lança uma ValueError se separator ou enclosure não tiver comprimento de um byte.

Lança uma ValueError se escape não tiver comprimento de um byte ou se for uma string vazia.

Registro de Alterações

Versão Descrição
8.4.0 Depender do valor padrão de escape agora está descontinuado.
8.3.0 Uma string vazia é retornada ao invés de uma string com um único byte nulo para o último campo, se ele contiver apenas um demarcador não terminado.
8.0.0 O parâmetro length agora pode ser nulo.
7.4.0 O parâmetro escape agora aceita uma string vazia para desabilitar o mecanismo de escape proprietário.

Exemplos

Exemplo #1 Lê e imprime todo o conteúdo de um arquivo CSV

<?php
$row
= 1;
if ((
$handle = fopen("teste.csv", "r")) !== FALSE) {
while ((
$data = fgetcsv($handle, 1000, ",")) !== FALSE) {
$num = count($data);
echo
"<p> $num campos na linha $row: <br /></p>\n";
$row++;
for (
$c=0; $c < $num; $c++) {
echo
$data[$c] . "<br />\n";
}
}
fclose($handle);
}
?>

Veja Também