fputcsv

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

fputcsvFormata a linha como CSV e a escreve em um ponteiro de arquivo

Descrição

fputcsv(
    resource $stream,
    array $fields,
    string $separator = ",",
    string $enclosure = "\"",
    string $escape = "\\",
    string $eol = "\n"
): int|false

fputcsv() formata uma linha (passada como um array de campos fields) como CSV e a escreve (terminando com uma nova linha eol) no fluxo de arquivo especificado por stream.

Parâmetros

stream

O ponteiro de arquivo deve ser válido e deve apontar para um arquivo aberto com sucesso por fopen() ou fsockopen() (e ainda não fechado por fclose()).

fields

Um array de strings.

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.

eol

O parâmetro opcional eol define uma sequência customizada de Fim de Linha.

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.

Nota:

Se um caractere enclosure estiver contido em um campo, ele sofrerá escape por duplicação, a menos que seja imadiatamente precedido por um escape.

Valor Retornado

Retorna o comprimento da string escrita ou false em caso de falha.

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.1.0 O parâmetro opcional eol foi adicionado.
7.4.0 O parâmetro escape agora aceita uma string vazia para desabilitar o mecanismo de escape proprietário.

Exemplos

Exemplo #1 Exemplo da fputcsv()

<?php

$lista
= [
[
'aaa', 'bbb', 'ccc', 'dddd'],
[
'123', '456', '789'],
[
'"aaa"', '"bbb"']
];

$fp = fopen('file.csv', 'w');

foreach (
$lista as $linha) {
fputcsv($fp, $linha, ',', '"', '');
}

fclose($fp);
?>

O exemplo acima irá escrever o seguinte no arquivo file.csv:

aaa,bbb,ccc,dddd
123,456,789
"""aaa""","""bbb"""

Veja Também