fputcsv()

A função fputcsv() formata uma única linha de dados — fornecida como um array PHP — em uma linha CSV (valores separados por vírgula) e a escreve em um arquivo aberto. É a maneira padrão de exportar dados tabulares como relatórios, exportações de banco de dados ou planilhas que os usuários abrirão no Excel, Google Sheets ou LibreOffice.

Esta página aborda a sintaxe e os parâmetros, o loop de escrita típico, como fputcsv() coloca aspas e escapa caracteres especiais automaticamente, como controlar o delimitador e o delimitador de campo, e as armadilhas mais comuns (a nova linha no final, UTF-8 no Excel e a mudança no padrão do parâmetro $escape).

Sintaxe

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

Valor de retorno: o número de bytes escritos, ou false em caso de falha.

O parâmetro $eol está disponível a partir do PHP 8.1, e o PHP 9.0 altera o valor padrão de $escape de "\\" para "". Se você quiser uma saída estável e portável hoje, passe escape: "" explicitamente.

Como fputcsv() Funciona

fputcsv() recebe um array e escreve exatamente uma linha. Para exportar uma tabela, você a chama uma vez por linha dentro de um loop. A função gerencia as aspas por você: qualquer campo que contenha o separador, o delimitador de campo ou uma quebra de linha é automaticamente envolvido pelo caractere de delimitação, e as aspas incorporadas são duplicadas.

O fluxo de trabalho básico é:

1. Construir um array (ou array de arrays) com os dados a exportar.
2. Abrir o arquivo de destino para escrita com fopen().
3. Chamar fputcsv() uma vez por linha.
4. Fechar o arquivo com fclose().

Exemplo Básico: Escrevendo um Arquivo CSV

<?php

$data = [
    ['Name', 'Surname', 'Age', 'Gender'], // header row
    ['John', 'Doe', '30', 'Male'],
    ['Jane', 'Doe', '25', 'Female'],
    ['Bob', 'Smith', '40', 'Male'],
];

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

foreach ($data as $row) {
    fputcsv($file, $row);
}

fclose($file);

// Show what was written:
echo file_get_contents('people.csv');

Saída:

Name,Surname,Age,Gender
John,Doe,30,Male
Jane,Doe,25,Female
Bob,Smith,40,Male

O primeiro array é escrito como uma linha de cabeçalho, e cada array subsequente se torna uma linha de dados.

Aspas e Escape Automáticos

Você não precisa colocar aspas nos campos manualmente — fputcsv() decide quando as aspas são necessárias. Um campo é delimitado apenas se contiver o delimitador, uma quebra de linha ou o próprio caractere de delimitação.

<?php

$file = fopen('php://output', 'w'); // write straight to the browser/CLI

fputcsv($file, ['Plain', 'Has, comma', 'Has "quotes"', "Two\nlines"]);

fclose($file);

Saída:

Plain,"Has, comma","Has ""quotes""","Two
lines"

Observe que Plain é deixado como está, o campo com vírgula é envolvido em aspas, as aspas duplas incorporadas são duplicadas (""), e o valor com uma quebra de linha é delimitado para que a quebra de linha sobreviva. O stream php://output é útil para testes ou para transmitir um download sem um arquivo temporário.

Delimitador e Caractere de Delimitação Personalizados

Para produzir um arquivo separado por tabulação ou por ponto e vírgula, passe o argumento $separator. Muitos locais europeus abrem arquivos delimitados por ponto e vírgula de forma mais limpa no Excel.

<?php

$file = fopen('php://output', 'w');

// Semicolon delimiter
fputcsv($file, ['John', 'Doe', '30'], ';');

// Tab delimiter
fputcsv($file, ['Jane', 'Doe', '25'], "\t");

fclose($file);

Saída:

John;Doe;30
Jane	Doe	25

Armadilhas Comuns

• Nova linha no final. fputcsv() sempre acrescenta um terminador de linha, portanto o arquivo termina com uma linha em branco. Ao lê-lo posteriormente com fgetcsv(), isso é inofensivo, mas pode surpreender em comparações byte a byte.
• UTF-8 no Excel. O Excel precisa de um BOM UTF-8 para renderizar corretamente caracteres acentuados. Escreva um antes da primeira linha: fwrite($file, "\xEF\xBB\xBF");. Consulte fwrite().
• O parâmetro $escape. O escape legado com barra invertida pode corromper campos que legitimamente contêm \. Passe escape: "" (PHP 7.4+) para uma saída RFC 4180 limpa; isso também corresponde ao novo padrão do PHP 9.
• Sempre verifique o valor de retorno. fputcsv() retorna false em caso de falha (por exemplo, disco cheio ou stream somente leitura). Envolva as escritas em tratamento de erros para exportações em produção.
• Alternativa conveniente. Para despejar uma string inteira em um arquivo em uma única chamada, consulte file_put_contents(); use fputcsv() quando precisar de escape CSV adequado por linha.

Lendo o Arquivo de Volta

O contraponto natural de fputcsv() é fgetcsv(), que analisa uma linha CSV de volta em um array:

<?php

$file = fopen('people.csv', 'r');

while (($row = fgetcsv($file)) !== false) {
    echo implode(' | ', $row), PHP_EOL;
}

fclose($file);

Se você já tiver uma string CSV na memória em vez de um arquivo, use str_getcsv().

Conclusão

fputcsv() é a maneira idiomática de exportar dados de array para CSV em PHP: ela lida automaticamente com aspas de delimitador e escape de aspas, suporta separadores personalizados e se combina naturalmente com fopen() e fclose(). Para saída portável, passe escape: "", e adicione um BOM UTF-8 quando o arquivo for destinado ao Excel. Para ler os dados de volta, use fgetcsv().

Prática