Introdução à Criação e Manipulação de Arquivos em PHP

O PHP é executado no servidor, portanto pode ler e escrever arquivos reais em disco — relatórios gerados, HTML em cache, entradas de log, CSVs exportados, conteúdo enviado por usuários e configurações. Este capítulo abrange o fluxo de trabalho principal para criar e escrever arquivos: abrir um manipulador de arquivo com o modo correto, escrever dados e fechar o manipulador. Também explica quando usar os auxiliares mais simples de uma linha.

Existem duas famílias de ferramentas de escrita de arquivos em PHP:

• Manipuladores de stream — fopen() / fwrite() / fclose(). Ideal quando você escreve de forma incremental (acrescentando linhas de log, transmitindo saída grande) e quer controle fino sobre o modo do arquivo.
• Auxiliares de chamada única — file_put_contents(). Ideal quando você tem a string completa na memória e quer apenas gravá-la em um arquivo em uma única chamada.

Usaremos a abordagem de stream primeiro, porque entender os modos é a chave para todo o resto.

Criando e escrevendo um arquivo com fopen()

Para escrever em um arquivo, primeiro abra-o com fopen(). Ele recebe o caminho do arquivo e uma string de modo, e retorna um manipulador de arquivo (um resource) sobre o qual as outras funções operam:

<?php
$file = fopen("example.txt", "w");   // open for writing, truncating the file
fwrite($file, "This is an example.\n");
fclose($file);                       // always close the handle

O que cada linha faz:

• fopen("example.txt", "w") abre example.txt no modo de escrita. Se o arquivo não existir, ele é criado; se existir, seu conteúdo é apagado (truncado para zero bytes).
• fwrite() escreve a string no arquivo e retorna o número de bytes gravados (ou false em caso de falha).
• fclose() descarrega todos os dados em buffer e libera o manipulador. Omitir essa chamada pode deixar dados não gravados até o fim do script.

Um caminho relativo como "example.txt" é resolvido em relação ao diretório de trabalho atual do script. Para maior segurança e previsibilidade, prefira um caminho absoluto, por ex. __DIR__ . "/example.txt".

Modos de arquivo

O modo passado para fopen() determina se o arquivo é criado, truncado ou acrescentado, e se você pode lê-lo. Estes são os modos que importam para criar e escrever:

Use "x" quando não puder sobrescrever um arquivo existente — por exemplo, ao escrever um arquivo de lock. Use "a" para logs, onde cada execução deve adicionar ao arquivo em vez de apagá-lo.

Acrescentar em vez de sobrescrever

Um erro muito comum é usar "w" para um log e depois se perguntar por que o arquivo tem apenas uma linha. Abra com "a" para manter o conteúdo anterior e adicionar ao final:

<?php
$log = fopen("app.log", "a");        // append mode — never erases
fwrite($log, "[" . date("Y-m-d H:i:s") . "] User logged in\n");
fclose($log);

Execute isso duas vezes e o arquivo terá duas linhas com timestamp em vez de uma.

O atalho: file_put_contents()

Quando você já tem o conteúdo completo como string, file_put_contents() realiza abertura, escrita e fechamento em uma única chamada:

<?php
// Overwrite (or create) the file with this exact content:
file_put_contents("greeting.txt", "Hello, world!\n");

// Append instead of overwriting:
file_put_contents("app.log", "another line\n", FILE_APPEND);

Retorna o número de bytes gravados ou false em caso de falha. Esta é a escolha mais limpa para payloads pequenos em memória. Recorra a fopen()/fwrite() quando escrever em um loop ou precisar manter o manipulador aberto entre várias operações.

Lendo de volta o que você escreveu

Para confirmar uma escrita, abra o arquivo no modo de leitura ("r") e leia-o. O capítulo complementar PHP File Open/Read cobre isso em profundidade, mas a versão com stream é:

<?php
$file = fopen("example.txt", "r");
$contents = fread($file, filesize("example.txt"));
fclose($file);
echo $contents;

Aqui fread() lê até filesize("example.txt") bytes — o arquivo inteiro — em $contents. Para uma linha única, file_get_contents() lê o arquivo inteiro em uma string sem manipulador para gerenciar.

Tratando erros e arquivos ausentes

fopen() retorna false (e emite um aviso) se não conseguir abrir o arquivo — permissões incorretas, diretório inexistente ou disco somente leitura. Sempre verifique antes de escrever:

<?php
$file = fopen("/no/such/dir/example.txt", "w");
if ($file === false) {
    echo "Could not open the file for writing.";
} else {
    fwrite($file, "ok");
    fclose($file);
}

Antes de ler um arquivo que você não criou na mesma execução, confirme que ele existe com file_exists() para evitar avisos de filesize() ou fread().

Outras funções úteis para arquivos

Além de criar e escrever, o PHP inclui um kit completo de ferramentas para gerenciamento de arquivos:

• file_get_contents() — lê um arquivo inteiro em uma string em uma única chamada.
• file_put_contents() — escreve uma string em um arquivo em uma única chamada.
• file_exists() — verifica se um caminho existe antes de agir sobre ele.
• unlink() — exclui um arquivo.
• rename() — renomeia ou move um arquivo.
• copy() — copia um arquivo para um novo caminho.

Para arquivos enviados por formulário, veja PHP File Upload, e para uma visão mais abrangente da API de sistema de arquivos, veja PHP File Handling.

Resumo

• Abra um arquivo com fopen($path, $mode); o modo controla o comportamento de criar/truncar/acrescentar.
• Use "w" para sobrescrever, "a" para acrescentar e "x" para recusar sobrescrever um arquivo existente.
• fwrite() escreve e fclose() descarrega e libera o manipulador — sempre feche.
• Para escritas de string completa, file_put_contents() é a alternativa concisa de uma única chamada.
• Verifique o valor de retorno de fopen() e use file_exists() para escrever código robusto e sem avisos.

Prática