fputcsv()

La función fputcsv() formatea una sola fila de datos —proporcionada como un array de PHP— en una línea CSV (valores separados por comas) y la escribe en un archivo abierto. Es la forma estándar de exportar datos tabulares como informes, exportaciones de bases de datos u hojas de cálculo que los usuarios abrirán en Excel, Google Sheets o LibreOffice.

Esta página cubre la sintaxis y los parámetros, el bucle de escritura típico, cómo fputcsv() entrecomilla y escapa caracteres especiales automáticamente, cómo controlar el delimitador y el delimitador de encierro, y los errores más comunes (la nueva línea al final, el UTF-8 en Excel y el cambio en el valor predeterminado del parámetro $escape).

Sintaxis

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

Valor de retorno: el número de bytes escritos, o false en caso de error.

El parámetro $eol está disponible desde PHP 8.1, y PHP 9.0 cambia el valor predeterminado de $escape de "\\" a "". Si deseas una salida estable y portable hoy, pasa escape: "" explícitamente.

Cómo funciona fputcsv()

fputcsv() toma un array y escribe exactamente una línea. Para exportar una tabla, se llama una vez por fila dentro de un bucle. La función gestiona el entrecomillado automáticamente: cualquier campo que contenga el separador, el carácter de encierro o una nueva línea es envuelto automáticamente en el carácter de encierro, y las comillas incrustadas se duplican.

El flujo de trabajo básico es:

1. Construir un array (o array de arrays) con los datos a exportar.
2. Abrir el archivo de destino para escritura con fopen().
3. Llamar a fputcsv() una vez por fila.
4. Cerrar el archivo con fclose().

Ejemplo básico: escribir un archivo 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');

Salida:

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

El primer array se escribe como fila de encabezado y cada array posterior se convierte en una línea de datos.

Entrecomillado y escape automáticos

No es necesario entrecomillar los campos manualmente: fputcsv() decide cuándo se requiere el entrecomillado. Un campo solo se encierra si contiene el delimitador, un salto de línea o el carácter de encierro.

<?php

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

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

fclose($file);

Salida:

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

Nótese que Plain se deja tal cual, el campo que contiene la coma se envuelve en comillas, las comillas dobles incrustadas se duplican (""), y el valor con una nueva línea queda encerrado para que el salto de línea se preserve. El flujo php://output es muy útil para pruebas o para transmitir una descarga sin un archivo temporal.

Delimitador y encierro personalizados

Para producir un archivo separado por tabulaciones o punto y coma, pasa el argumento $separator. Muchos entornos europeos abren archivos delimitados por punto y coma de forma más limpia en Excel.

<?php

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

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

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

fclose($file);

Salida:

John;Doe;30
Jane	Doe	25

Errores comunes

• Nueva línea al final. fputcsv() siempre añade un terminador de línea, por lo que el archivo termina con una línea en blanco. Al leerlo posteriormente con fgetcsv() esto no causa problemas, pero puede sorprender en comparaciones byte a byte.
• UTF-8 en Excel. Excel necesita un BOM UTF-8 para mostrar correctamente los caracteres acentuados. Escríbelo antes de la primera fila: fwrite($file, "\xEF\xBB\xBF");. Consulta fwrite().
• El parámetro $escape. El escape heredado con barra invertida puede corromper campos que legítimamente contienen \. Pasa escape: "" (PHP 7.4+) para una salida RFC 4180 limpia; esto también coincide con el nuevo valor predeterminado de PHP 9.
• Comprueba siempre el valor de retorno. fputcsv() devuelve false en caso de error (por ejemplo, disco lleno o flujo de solo lectura). Envuelve las escrituras en manejo de errores para exportaciones en producción.
• Alternativa práctica. Para volcar una cadena completa a un archivo en una sola llamada, consulta file_put_contents(); usa fputcsv() cuando necesites el escape CSV adecuado por fila.

Leer el archivo de nuevo

El complemento natural de fputcsv() es fgetcsv(), que analiza una línea CSV de vuelta en un array:

<?php

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

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

fclose($file);

Si ya tienes una cadena CSV en memoria en lugar de un archivo, usa str_getcsv() en su lugar.

Conclusión

fputcsv() es la forma idiomática de exportar datos de array a CSV en PHP: gestiona automáticamente el entrecomillado de delimitadores y el escape de comillas, admite separadores personalizados y se combina de forma natural con fopen() y fclose(). Para una salida portable, pasa escape: "", y añade un BOM UTF-8 cuando el archivo esté destinado a Excel. Para leer los datos de nuevo, utiliza fgetcsv().

Práctica