PHP Filesystem

Introdução

As funções de sistema de arquivos do PHP permitem que seus scripts leiam e gravem no disco do servidor: criando, lendo, atualizando e excluindo arquivos, além de gerenciar diretórios. Elas são a base de tudo o que precisa persistir dados fora de um banco de dados — arquivos de log, relatórios gerados, arquivos enviados por usuários, configurações, caches e tarefas de importação/exportação.

Este artigo explica as duas principais formas de trabalhar com arquivos (a família baseada em handle construída em torno de fopen(), e os helpers de chamada única como file_get_contents()), mostra exemplos executáveis para cada uma e aponta as armadilhas de permissão e tratamento de erros que costumam causar problemas em produção.

Duas formas de trabalhar com arquivos

O PHP oferece dois estilos, e escolher o correto mantém o código simples:

1. Helpers de chamada única — file_get_contents() e file_put_contents() leem ou gravam um arquivo inteiro em uma única chamada. Use-os quando o arquivo cabe confortavelmente na memória (arquivos de configuração, JSON/CSV pequenos, templates). São a opção mais curta e legível.
2. Funções baseadas em handle — fopen(), fread(), fwrite() e fclose() fornecem um handle de arquivo (um recurso) que você lê ou grava de forma incremental. Use-os para arquivos grandes que você deseja transmitir linha por linha sem carregar tudo na memória, ou quando precisar manter um arquivo aberto durante várias operações.

Operações com Arquivos

O PHP fornece várias funções para trabalhar com arquivos. Essas funções permitem criar, abrir, ler, gravar e excluir arquivos. As funções de arquivo mais usadas incluem:

• fopen(): Abre um arquivo e retorna um handle. Recebe dois argumentos: o nome do arquivo e o modo no qual abri-lo (veja a tabela abaixo).
• fclose(): Fecha um handle de arquivo aberto e libera quaisquer gravações em buffer para o disco.
• fwrite(): Grava uma string em um arquivo aberto, retornando o número de bytes gravados.
• fread(): Lê uma determinada quantidade de bytes de um arquivo aberto.
• feof(): Retorna true quando o fim do arquivo é atingido — útil como condição de loop durante a leitura.
• unlink(): Exclui um arquivo.
• filesize(): Retorna o tamanho de um arquivo em bytes.
• file_exists(): Verifica se um arquivo ou diretório existe antes de agir sobre ele.

Para tarefas simples de leitura/gravação, prefira file_get_contents() e file_put_contents(), que tratam abertura, leitura/gravação e fechamento em uma única chamada.

Modos de arquivo para fopen()

O segundo argumento de fopen() controla o que você pode fazer com o handle e o que acontece com o conteúdo existente. Os modos mais comuns são:

Atenção: "w" apaga o conteúdo existente no momento em que você abre o arquivo. Se quiser adicionar a um log em vez de sobrescrevê-lo, use "a".

Operações com Diretórios

O PHP também fornece funções para trabalhar com diretórios. Essas funções permitem criar, excluir e manipular diretórios. Algumas das funções de diretório mais usadas incluem:

• mkdir(): Esta função é usada para criar um diretório.
• rmdir(): Esta função é usada para excluir um diretório.
• opendir(): Esta função é usada para abrir um diretório.
• readdir(): Esta função é usada para ler o conteúdo de um diretório.
• closedir(): Esta função é usada para fechar um diretório aberto.

Exemplos

Vejamos como essas funções são usadas na prática.

Criando e gravando em um arquivo

Para criar um arquivo e gravar nele, abra-o no modo de gravação com fopen(), grave com fwrite() e sempre use fclose():

<?php

$file = fopen("example.txt", "w");
if ($file === false) {
    exit("Error opening file");
}
fwrite($file, "Hello, world!");
fclose($file);

Isso cria example.txt no mesmo diretório do script (substituindo-o se já existir), grava Hello, world! e fecha o handle.

A mesma tarefa com o helper de chamada única é uma única linha — este é o estilo preferido para arquivos pequenos:

<?php

file_put_contents("example.txt", "Hello, world!");

Lendo um arquivo

Para ler um arquivo com um handle, abra-o no modo de leitura e use fread(). Passar filesize() informa ao fread() quantos bytes ler:

<?php

$file = fopen("example.txt", "r");
if ($file === false) {
    exit("Error opening file");
}
echo fread($file, filesize("example.txt"));
fclose($file);

Para arquivos pequenos, file_get_contents() faz o mesmo em uma chamada:

<?php

echo file_get_contents("example.txt");

Lendo um arquivo linha por linha

Para arquivos grandes, leia linha por linha com fgets() para nunca carregar o arquivo inteiro na memória. O loop é executado até que feof() sinalize o fim do arquivo:

<?php

$file = fopen("example.txt", "r");
if ($file === false) {
    exit("Error opening file");
}
while (!feof($file)) {
    $line = fgets($file);
    echo $line;
}
fclose($file);

Anexando a um arquivo

Para adicionar conteúdo a um arquivo sem apagar o que já está lá, abra-o no modo de anexação ("a"). Este é o modo correto para logs:

<?php

$file = fopen("log.txt", "a");
fwrite($file, "New log entry\n");
fclose($file);

Criando um Diretório

Para criar um diretório, use a função mkdir():

<?php

mkdir("example_directory");

Isso cria um diretório chamado example_directory ao lado do script. Para criar diretórios aninhados em uma única chamada, passe o modo e o sinalizador recursivo:

<?php

mkdir("parent/child/grandchild", 0755, true);

Nota: mkdir() requer permissão de gravação no diretório pai. O terceiro argumento (true) habilita a criação recursiva de diretórios intermediários.

Excluindo um Arquivo

Para excluir um arquivo, use a função unlink():

<?php

if (file_exists("example.txt")) {
    unlink("example.txt");
}

Verificar com file_exists() primeiro evita um aviso quando o arquivo já foi removido.

Boas práticas

• Sempre feche os handles. Cada fopen() deve ser pareado com fclose() para que as gravações em buffer sejam liberadas e o recurso seja descartado.
• Verifique os valores de retorno. fopen(), mkdir() e unlink() retornam false em caso de falha — proteja-se contra isso em vez de assumir sucesso.
• Atenção às permissões. A maioria dos erros de "permissão negada" ocorre porque o usuário do servidor web não é proprietário do diretório de destino, não por causa do seu código.
• Escolha a ferramenta certa. Use file_get_contents() / file_put_contents() para operações com o arquivo inteiro; use a família fopen()/fread() apenas quando precisar de streaming.

Conclusão

As funções de sistema de arquivos fornecem a base para o gerenciamento de arquivos e diretórios no PHP. Ao compreender a diferença entre helpers de chamada única e streaming baseado em handle, escolhendo o modo correto de fopen() e fechando handles com segurança, você pode criar aplicações robustas que armazenam dados e configurações de forma confiável. Para se aprofundar, explore PHP File Handling, PHP File Open/Read e trabalhando com diretórios.

Prática