Manipulação de Arquivos em PHP

A manipulação de arquivos é uma das tarefas mais comuns na programação do lado do servidor: gravar logs, gerar relatórios, armazenar dados em cache, importar arquivos CSV e servir downloads — tudo depende disso. O PHP traz um conjunto rico de funções nativas para trabalhar com arquivos, por isso raramente é necessário recorrer a uma biblioteca externa.

Este capítulo cobre o ciclo de vida completo de um arquivo — criar, ler, atualizar e excluir (CRUD) — e explica quando usar cada abordagem. De forma geral, o PHP oferece dois estilos:

• Helpers de arquivo inteiro (file_get_contents(), file_put_contents()) — uma linha, perfeitos para arquivos pequenos que cabem na memória.
• Funções baseadas em stream (fopen(), fread(), fwrite(), fgets(), fclose()) — fornecem um handle para ler ou gravar um arquivo grande pedaço por pedaço, sem carregá-lo todo de uma vez.

Saber qual usar é a diferença entre um código que funciona com um arquivo de configuração de 2 KB e um código que sobrevive a um arquivo de log de 2 GB.

Modos de Arquivo

Toda chamada baseada em stream começa com fopen($filename, $mode), e o modo é a parte que os iniciantes erram com mais frequência. Ele decide se o arquivo é aberto para leitura, escrita ou ambos, se o conteúdo existente é apagado e onde o ponteiro interno começa.

Adicione "b" (ex.: "rb", "wb") para acesso seguro a binários quando trabalhar com imagens, PDFs ou qualquer dado não textual — isso evita a conversão de finais de linha no Windows.

Criando e Gravando um Arquivo

Para criar um arquivo, abra-o em modo de escrita com fopen() e grave com fwrite(). Sempre feche o handle com fclose() ao terminar — isso descarrega o buffer para o disco e libera o recurso.

<?php
$file = fopen("test.txt", "w");   // create/truncate, open for writing
fwrite($file, "Hello World\n");
fwrite($file, "Second line\n");   // each call appends after the previous one
fclose($file);                    // flush to disk and release the handle

Abrir com "w" apaga qualquer conteúdo existente. Para adicionar a um arquivo sem destruir o que já está lá, abra-o em modo de concatenação ("a") em vez disso:

<?php
$log = fopen("app.log", "a");     // pointer starts at end of file
fwrite($log, "User logged in at " . date("H:i:s") . "\n");
fclose($log);

Para uma linha rápida quando você já tem a string inteira na memória, ignore o handle completamente e use file_put_contents():

<?php
file_put_contents("test.txt", "Hello World\n");          // overwrite
file_put_contents("app.log", "another line\n", FILE_APPEND); // append

Sempre verifique o valor de retorno de fopen(). Se o caminho estiver errado ou o diretório não tiver permissão de escrita, a função retorna false e o PHP emite um aviso — usar false como handle vai falhar silenciosamente.

<?php
$file = fopen("/protected/test.txt", "w");
if ($file === false) {
    die("Could not open the file for writing.");
}
fwrite($file, "data");
fclose($file);

Lendo um Arquivo

A forma mais simples de ler um arquivo pequeno é file_get_contents(), que retorna o conteúdo inteiro como uma única string:

<?php
$content = file_get_contents("test.txt");
echo $content;          // prints everything in the file

Quando o arquivo é grande, carregar tudo na memória é um desperdício. Leia-o linha por linha com fgets(), em loop até que feof() (fim de arquivo) seja atingido:

<?php
$file = fopen("test.txt", "r");
while (!feof($file)) {
    $line = fgets($file);   // reads one line, including the newline
    echo $line;
}
fclose($file);

Se quiser cada linha como um elemento de array em uma única chamada, file() é conveniente — mas, assim como file_get_contents(), carrega o arquivo inteiro na memória:

<?php
$lines = file("test.txt");          // array, one element per line
echo "This file has " . count($lines) . " lines.";

Um bom hábito é confirmar se o arquivo existe antes de lê-lo, usando file_exists() (ou is_readable() para também verificar as permissões):

<?php
if (file_exists("test.txt")) {
    echo file_get_contents("test.txt");
} else {
    echo "File not found.";
}

Atualizando um Arquivo

Para substituir o conteúdo de um arquivo, a ferramenta mais simples é file_put_contents(). Ela abre, grava e fecha em uma única chamada:

<?php
$content = "Hello World Again\n";
file_put_contents("test.txt", $content);   // replaces the old contents

Para adicionar a um arquivo em vez de substituí-lo, passe a flag FILE_APPEND (mostrado acima) ou abra-o em modo de concatenação com fopen(). Não existe uma função para "editar a linha 3" — para alterar parte de um arquivo, normalmente você o lê, modifica os dados em PHP e os grava novamente.

Excluindo um Arquivo

Use unlink() — atenção ao nome incomum — para remover um arquivo. Ele retorna true em caso de sucesso e false em caso de falha, por isso proteja com file_exists() para evitar um aviso:

<?php
if (file_exists("test.txt")) {
    if (unlink("test.txt")) {
        echo "File deleted.";
    } else {
        echo "Could not delete the file.";
    }
} else {
    echo "Nothing to delete.";
}

unlink() remove apenas arquivos. Para excluir um diretório vazio, use rmdir(); consulte PHP Directory para trabalhar com pastas.

Quando Usar Cada Abordagem

• Arquivos de texto/configuração pequenos, conteúdo inteiro de uma vez → file_get_contents() / file_put_contents().
• Arquivos grandes, streaming linha por linha → fopen() + fgets() / fread().
• Concatenar a um log → modo "a", ou FILE_APPEND.
• Criar um arquivo somente se ainda não existir → modo "x".
• Dados binários (imagens, PDFs) → adicione a flag "b" e use fread()/fwrite().

Resumo

A manipulação de arquivos é uma parte essencial do PHP do lado do servidor. Você aprendeu as duas famílias de funções — os helpers de arquivo inteiro de uma linha e as funções de handle baseadas em stream — e quando cada uma é adequada, como os modos de arquivo controlam truncamento e concatenação, como ler arquivos grandes de forma eficiente com fgets()/feof(), e como atualizar e excluir arquivos com segurança.

Para se aprofundar, explore os capítulos dedicados: Create and Write a File, Open and Read a File, PHP Filesystem functions, File Upload, e PHP Directory.

Prática