fwrite()

O Que É a Função fwrite()?

fwrite() é uma função PHP nativa que escreve uma string em um arquivo aberto. A escrita começa na posição atual do ponteiro do arquivo e avança esse ponteiro pelo número de bytes escritos, fazendo com que chamadas consecutivas concatenem os dados em vez de sobrescrever. É a maneira padrão de baixo nível para escrever em arquivos no PHP e também é comumente apelidada de fputs() (as duas são idênticas).

Esta página aborda a sintaxe, o argumento opcional length, os modos de arquivo que controlam onde e como os dados são escritos, valores de retorno, tratamento de erros e as tarefas cotidianas para as quais você vai recorrer ao fwrite().

Sintaxe

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

Valor de retorno: o número de bytes efetivamente escritos, ou false em caso de falha. Como uma escrita parcial (menos bytes do que strlen($data)) é possível em alguns streams, um código robusto verifica o valor de retorno em vez de assumir o sucesso.

Você quase nunca precisa do argumento length. fwrite($file, $data) já escreve a string inteira. Passe um comprimento apenas quando quiser deliberadamente truncar a saída para os primeiros N bytes.

Um Exemplo Básico

<?php

$filename = 'myfile.txt';
$file = fopen($filename, 'w');     // open for writing (truncates the file)

if ($file === false) {
    exit("Could not open $filename for writing");
}

$bytes = fwrite($file, "Hello, world!");
fclose($file);

echo "Wrote $bytes bytes."; // Wrote 13 bytes.

Três passos estão sempre envolvidos:

1. Abra o arquivo com fopen() em um modo que permita escrita.
2. Chame fwrite() uma ou mais vezes para enviar dados ao stream.
3. Feche o arquivo com fclose() para liberar o buffer e o identificador.

"Hello, world!" tem 13 caracteres, portanto fwrite() retorna 13.

Modos de Arquivo: Para Onde Vão os Bytes

O comportamento de fwrite() é decidido quase inteiramente pelo modo que você passou para fopen(). Esta é a fonte de confusão mais comum, por isso vale a pena memorizar:

Se seu arquivo continua saindo vazio ou perdendo os dados do dia anterior, você quase certamente o abriu com 'w' quando quis dizer 'a'.

Anexar em Vez de Sobrescrever

<?php

$log = fopen('app.log', 'a');           // 'a' keeps existing lines
fwrite($log, "User logged in\n");       // \n adds a newline
fwrite($log, "Order placed\n");
fclose($log);

Cada execução deste script adiciona mais duas linhas ao app.log em vez de apagá-lo.

Escrevendo Múltiplas Linhas

fwrite() escreve exatamente os bytes que você fornece — ele não adiciona quebras de linha. Inclua \n você mesmo (dentro de aspas duplas, para que o escape seja interpretado):

<?php

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

$names = ['Alice', 'Bob', 'Carol'];
foreach ($names as $name) {
    fwrite($file, $name . PHP_EOL); // PHP_EOL = OS-correct line ending
}

fclose($file);

PHP_EOL resolve para \n no Unix/macOS e \r\n no Windows, o que mantém os arquivos de texto portáveis.

Sempre Verifique o Valor de Retorno

Condições de disco cheio, problemas de permissão e pipes quebrados fazem com que as escritas falhem ou sejam incompletas. Trate o valor de retorno como a fonte da verdade:

<?php

$file = fopen('report.txt', 'w');
if ($file === false) {
    throw new RuntimeException('Unable to open report.txt');
}

$data    = str_repeat('x', 1000);
$written = fwrite($file, $data);

if ($written === false || $written < strlen($data)) {
    fclose($file);
    throw new RuntimeException('Write failed or incomplete');
}

fclose($file);
echo "OK: $written bytes written";

fwrite() vs file_put_contents()

Para uma única escrita rápida, file_put_contents() é mais conciso — ele abre, escreve e fecha em uma única chamada:

<?php

// Equivalent of the basic example above, in one line:
file_put_contents('myfile.txt', 'Hello, world!');

Prefira fwrite() quando precisar manter o arquivo aberto em várias escritas (loops, streaming, logging), passar opções como bloqueio, ou escrever incrementalmente sem reconstruir a string inteira na memória.

Armadilhas Comuns

• 'w' trunca imediatamente — no momento em que fopen($f, 'w') tem sucesso, o conteúdo antigo é perdido, mesmo que você nunca chame fwrite().
• Sem novas linhas automáticas — você deve adicionar \n / PHP_EOL você mesmo.
• Esquecer fclose() — os dados podem ficar em um buffer e nunca chegar ao disco até que o identificador seja fechado (ou o script termine).
• Aspas simples não expandem escapes — 'Line\n' escreve literalmente uma barra invertida seguida de n. Use "Line\n" para uma nova linha real.
• O limite de length é em bytes — com texto UTF-8 multibyte, um limite em bytes pode cortar um caractere ao meio.

Conclusão

fwrite() é a função central do PHP para escrever strings em um arquivo aberto. Domine o ciclo de três etapas abrir–escrever–fechar, escolha o modo correto em fopen() ('w' para substituir, 'a' para anexar), adicione suas próprias quebras de linha e verifique o valor de retorno, e você poderá escrever de arquivos de texto simples a logs de aplicação duráveis.

Funções Relacionadas

• fopen() — abrir o arquivo antes de escrever
• fclose() — liberar e fechar o identificador depois
• fread() e fgets() — ler os dados de volta
• file_put_contents() — escrever um arquivo inteiro em uma única chamada
• feof() — detectar o fim de um arquivo durante a leitura

Prática