PHP File Open: Um Guia para Ler e Escrever Arquivos em PHP

Ler e escrever arquivos é uma das tarefas mais comuns na programação do lado do servidor: você salva documentos enviados, gera logs, armazena dados em cache e lê arquivos de configuração. PHP oferece um conjunto pequeno e estável de funções para isso, e todas começam com uma única chamada — fopen(). Este capítulo explica como abrir um arquivo, ler seu conteúdo, escrever nele, adicionar dados ao final, fechá-lo e tratar os erros que inevitavelmente surgirão no caminho.

Entendendo a Função fopen()

A função fopen() abre um arquivo (ou uma URL) e retorna um manipulador de arquivo — um recurso que você passa para todas as outras funções de arquivo. Ela recebe dois argumentos obrigatórios: o caminho para o arquivo e o modo, que determina o que você tem permissão de fazer com ele e onde o ponteiro de arquivo interno (o cursor que marca sua posição) começa.

$handle = fopen("example.txt", "r");

Se o arquivo não puder ser aberto, fopen() retorna false e emite um aviso, portanto você sempre deve verificar o valor de retorno antes de usar o manipulador.

Modos de arquivo

O modo é o argumento mais importante: ele controla se o arquivo será lido, sobrescrito ou se dados serão adicionados ao final, e se um arquivo inexistente será criado.

Algumas regras importantes a lembrar:

• Use r quando o arquivo já deve existir e você só precisa lê-lo.
• w e w+ apagam o conteúdo do arquivo no momento em que ele é aberto — nunca os use quando quiser preservar dados existentes.
• a e a+ são a escolha segura para logs: sempre escrevem no final e nunca truncam.
• x e x+ protegem contra a sobrescrita acidental de um arquivo existente, o que é útil para operações de "criação única".

Observação: No Windows, acrescente b ao modo (por exemplo, rb, wb, ab) para abrir o arquivo em modo binário e evitar a conversão de quebras de linha que pode corromper arquivos não textuais. No Linux e no macOS, o sinalizador b é inofensivo, portanto adicioná-lo em todo lugar mantém seu código portável.

Lendo Arquivos em PHP

Para ler um arquivo, abra-o no modo de leitura (r) e use fread(). fread() recebe o manipulador de arquivo e o número de bytes a serem lidos; combiná-la com filesize() lê o arquivo inteiro de uma vez.

Aqui está um exemplo que lê todo o conteúdo de um arquivo:

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

Lendo um arquivo linha por linha

Para arquivos grandes, carregar tudo na memória é um desperdício. Use fgets() para ler uma linha por vez e feof() ("fim de arquivo") para parar quando chegar ao final:

<?php
$file = fopen("example.txt", "r");
if ($file) {
    while (!feof($file)) {
        $line = fgets($file);
        echo $line;
    }
    fclose($file);
}
?>

A alternativa mais curta: file_get_contents()

Para leituras simples em que você quer apenas o arquivo inteiro como uma string, file_get_contents() realiza a abertura, leitura e fechamento em uma única chamada:

<?php
$contents = file_get_contents("example.txt");
echo $contents;
?>

Use fopen() + fread()/fgets() quando precisar de controle granular (streaming, leituras parciais, bloqueio); recorra a file_get_contents() quando quiser simplesmente obter o texto do arquivo.

Escrevendo Arquivos em PHP

Para escrever em um arquivo, abra-o no modo de escrita (w) e use fwrite(). fwrite() recebe o manipulador de arquivo e a string a ser escrita, e retorna o número de bytes gravados (ou false em caso de falha). Lembre-se de que w trunca o arquivo primeiro, portanto ele sempre começa vazio.

Aqui está um exemplo que grava dados em um arquivo:

<?php
$file = fopen("example.txt", "w");
if ($file) {
    fwrite($file, "This is some data.");
    fclose($file);
}
?>

Assim como na leitura, existe um atalho de uma única chamada para escrita: file_put_contents() abre, escreve e fecha o arquivo em uma única instrução.

Adicionando Dados a Arquivos em PHP

Para adicionar dados ao final de um arquivo em PHP, você pode usar a função fopen() no modo de adição (a) e a função fwrite(). Isso permite que você adicione dados ao final de um arquivo, em vez de sobrescrevê-lo.

Aqui está um exemplo que adiciona dados a um arquivo:

<?php
$file = fopen("example.txt", "a");
if ($file) {
    fwrite($file, "This is some additional data.");
    fclose($file);
}
?>

Fechando Arquivos em PHP

É importante fechar um arquivo após terminar de trabalhar com ele, para liberar recursos do sistema e evitar a corrupção de dados. Isso pode ser feito com a função fclose(), que recebe o ponteiro de arquivo retornado por fopen() como argumento.

Aqui está um exemplo que demonstra a forma correta de fechar um arquivo em PHP:

<?php
$file = fopen("example.txt", "r");
if ($file) {
    // Perform file operations here
    fclose($file);
    echo "File closed successfully.";
}
?>

Tratamento de Erros em PHP

É importante tratar erros adequadamente ao trabalhar com arquivos em PHP. Por exemplo, se você tentar abrir um arquivo que não existe ou tentar escrever em um arquivo que não é gravável, receberá um erro.

Para tratar erros, você pode usar a instrução if e a variável $file retornada por fopen(). Se fopen() retornar false, significa que ocorreu um erro. Em ambientes de produção, você pode usar o operador de supressão de erros @ ou configurar um manipulador de erros personalizado para gerenciar avisos sem quebrar o layout da página.

Aqui está um exemplo que demonstra o tratamento de erros em PHP:

<?php
$file = fopen("example.txt", "r");
if ($file) {
    $contents = fread($file, filesize("example.txt"));
    fclose($file);
    echo $contents;
} else {
    echo "Error: Unable to open file.";
}
?>

Resumo

fopen() é a base do tratamento de arquivos em PHP. O modo escolhido define tudo: r lê, w sobrescreve, a adiciona ao final e x cria um arquivo apenas se ele ainda não existir. Leia com fread()/fgets(), escreva com fwrite(), sempre verifique se o manipulador é válido e feche-o com fclose() quando terminar. Para leituras e gravações simples de uma única vez, prefira file_get_contents() e file_put_contents().

Para se aprofundar, consulte fopen(), fread() e fwrite(), além dos capítulos mais amplos sobre PHP File Handling e PHP Filesystem.

Prática