file_put_contents()

A função file_put_contents() escreve uma string em um arquivo com uma única chamada. É a substituição moderna e de uma linha para a sequência clássica fopen() → fwrite() → fclose(): o PHP abre o arquivo, escreve os dados e fecha o identificador por você. Esta página aborda sua sintaxe, parâmetros, valor de retorno, flags para anexar e bloquear, e os erros que mais frequentemente causam problemas.

Sintaxe

file_put_contents(string $filename, mixed $data, int $flags = 0, ?resource $context = null): int|false

Parâmetros

Valor de retorno

file_put_contents() retorna o número de bytes escritos, ou false em caso de falha. Como 0 é um resultado válido (mas falsy) quando você escreve uma string vazia, sempre verifique falhas com a comparação estrita === false em vez de um teste de veracidade genérico.

Escrevendo um arquivo

Por padrão, a função sobrescreve o conteúdo existente do arquivo (ou cria o arquivo se ele não existir):

<?php

$filename = 'myfile.txt';
$data     = 'This is some data to be written to the file.';

$bytes = file_put_contents($filename, $data);

if ($bytes === false) {
    echo "Failed to write to $filename";
} else {
    echo "Wrote $bytes bytes to $filename";
}

Saída:

Wrote 44 bytes to myfile.txt

O contador retornado, 44, é o comprimento da string em bytes.

Anexando em vez de sobrescrever

Passe a flag FILE_APPEND para adicionar ao final do arquivo em vez de substituir seu conteúdo — útil para arquivos de log:

<?php

$log = 'app.log';

file_put_contents($log, "First line\n", FILE_APPEND);
file_put_contents($log, "Second line\n", FILE_APPEND);

echo file_get_contents($log);

Saída:

First line
Second line

Sem FILE_APPEND, a segunda chamada apagaria a primeira linha.

Bloqueando o arquivo durante a escrita

Se vários processos puderem escrever no mesmo arquivo ao mesmo tempo, adicione LOCK_EX para adquirir um bloqueio exclusivo durante a escrita. Combine flags com o operador OR bit a bit (|):

<?php

file_put_contents('counter.txt', "ping\n", FILE_APPEND | LOCK_EX);

Isso impede que dois escritores intercalem sua saída e corrompam o arquivo.

Escrevendo um array

Quando $data é um array, seus elementos string são concatenados sem separador. Você mesmo deve agrupá-los se precisar de delimitadores:

<?php

$lines = ['apple', 'banana', 'cherry'];

file_put_contents('fruits.txt', implode("\n", $lines));

echo file_get_contents('fruits.txt');

Saída:

apple
banana
cherry

Armadilhas comuns

• Falha silenciosa em permissões. Se o diretório não for gravável, a chamada retorna false e emite um aviso — não lança uma exceção. Verifique o valor de retorno (=== false) ou envolva a chamada e inspecione error_get_last().
• O diretório pai deve existir. file_put_contents() cria o arquivo, mas não os diretórios ausentes. Chame mkdir($dir, 0777, true) antes, se necessário.
• FILE_APPEND não é o mesmo que sobrescrever. Esquecer a flag é a causa mais comum de "meu log continua sendo apagado."
• Dados vazios são válidos. Escrever '' retorna 0, que é falsy — use === false para não confundir uma escrita vazia bem-sucedida com um erro.

Funções relacionadas

• file_get_contents() — o equivalente para leitura, que carrega um arquivo inteiro em uma string.
• fwrite() — escrita de nível mais baixo quando você precisa de um identificador aberto (ex.: muitas escritas pequenas em um loop).
• fopen() — abre um identificador de arquivo para leitura ou escrita em stream.
• file_exists() — verifica se um arquivo existe antes de escrever.

Conclusão

file_put_contents() é a maneira mais simples de escrever uma string em um arquivo em PHP: uma chamada abre, escreve e fecha o arquivo. Use FILE_APPEND para adicionar ao arquivo, LOCK_EX para escritores concorrentes, e sempre verifique o sucesso com uma verificação estrita === false.

Prática