fputs()

O que é a Função fputs()?

A função fputs() escreve uma string em um arquivo aberto. Ela é a ferramenta principal para salvar texto em disco no PHP: logs, exportações, arquivos de configuração gerados, entre outros.

O fato mais importante sobre fputs() é que ela é um alias de fwrite() — as duas funções são idênticas em todos os aspectos. O PHP mantém fputs() porque o nome pode ser lido como "file put string", o que é familiar para programadores vindos do C. Código novo geralmente prefere fwrite(), mas ambas se comportam da mesma forma, então tudo abaixo se aplica a qualquer um dos nomes.

Sintaxe

fputs(resource $stream, string $data, ?int $length = null): int|false

• $stream — um ponteiro de arquivo (um resource) retornado por fopen(). Este é o arquivo aberto no qual você está escrevendo, não um nome de arquivo.
• $data — a string a ser escrita.
• $length — opcional. Se fornecido, a escrita é interrompida após $length bytes, mesmo que $data seja mais longo.

Retorna o número de bytes escritos, ou false em caso de falha. Note que retorna 0, não false, quando não há nada a escrever, portanto sempre compare com === ao verificar erros.

Como Usar a Função fputs()

Escrever em um arquivo segue sempre um padrão de três etapas:

1. Abra o arquivo com fopen(), escolhendo um modo (veja abaixo).
2. Chame fputs() quantas vezes precisar.
3. Feche o arquivo com fclose() para liberar o buffer e o handle.

<?php

$file = fopen('myfile.txt', 'w');   // open for writing, truncating the file
fputs($file, "Hello, world!\n");    // write a line
fclose($file);                      // flush + release the handle

Após a execução, myfile.txt contém Hello, world! seguido de uma nova linha. O \n está entre aspas duplas para que o PHP o converta em uma quebra de linha real (um \n literal entre aspas simples seria escrito literalmente).

Escolhendo o Modo Correto do fopen()

O modo passado para fopen() determina onde fputs() escreve e se o conteúdo existente é preservado. Estes são os modos que permitem escrita:

Use 'w' para sobrescrever, e 'a' (append) para adicionar a um log sem perder o que já existe.

<?php

// Append three lines to a log; each run adds to the end.
$log = fopen('app.log', 'a');
fputs($log, "2026-06-21 user logged in\n");
fputs($log, "2026-06-21 report generated\n");
fclose($log);

Limitando a Quantidade de Bytes Escritos

O terceiro argumento opcional limita o número de bytes escritos. Isso é útil quando você quer apenas um prefixo de uma string maior:

<?php

$file = fopen('clip.txt', 'w');
$written = fputs($file, 'Hello, world!', 5);  // write only the first 5 bytes
fclose($file);

echo $written;   // 5  — the file now contains "Hello"

$written é 5, e clip.txt contém apenas Hello.

Sempre Verifique o Valor de Retorno

Uma escrita pode falhar — disco cheio, arquivo somente leitura ou handle fechado. Como fputs() pode legitimamente retornar 0, teste o resultado com a comparação estrita === false:

<?php

$file = fopen('out.txt', 'w');

if (fputs($file, 'data') === false) {
    echo 'Write failed!';
} else {
    echo 'Write succeeded.';
}

fclose($file);

Isso imprime Write succeeded. e evita o bug clássico em que if (!fputs(...)) trata erroneamente uma escrita de 0 bytes como um erro.

fputs() vs. file_put_contents()

fputs() precisa de um handle aberto e é ideal quando você escreve de forma incremental (muitas escritas pequenas, como em um loop de log). Quando você simplesmente quer despejar uma string inteira em um arquivo de uma vez, file_put_contents() faz o open/write/close em uma única chamada:

<?php

// Equivalent one-liner — no fopen()/fclose() needed.
file_put_contents('myfile.txt', "Hello, world!\n");

Use fputs()/fwrite() quando precisar de controle sobre o handle (adicionando em várias chamadas, escritas parciais); use file_put_contents() para escritas únicas e completas.

Resumo

• fputs() é um alias de fwrite() — mesmo comportamento, dois nomes.
• Escreve em um ponteiro de arquivo aberto de fopen(), portanto sempre combine com fclose().
• Retorna a contagem de bytes, ou false em caso de erro — verifique com === false.
• Use 'w' para sobrescrever e 'a' para acrescentar; um comprimento opcional limita os bytes escritos.
• Para uma única escrita de arquivo completo, prefira file_put_contents(). Para ler os dados de volta, veja fgets() e fread().

Prática