fclose()

Introdução à Função fclose() do PHP

A função fclose() fecha um ponteiro de arquivo que foi aberto anteriormente com fopen(). Um ponteiro de arquivo (também chamado de handle ou recurso de stream) é o valor que o PHP fornece quando abre um arquivo; todas as operações de leitura e escrita o utilizam para rastrear a posição atual no arquivo.

Fechar um handle quando você terminar é importante por dois motivos:

• Ele libera o buffer de escrita. O PHP e o sistema operacional não necessariamente gravam cada byte no disco imediatamente — eles mantêm os dados em um buffer por questões de desempenho. fclose() força a gravação de qualquer saída em buffer, de modo que um arquivo que você esqueceu de fechar pode acabar sem os seus últimos bytes.
• Ele libera recursos do sistema. Cada arquivo aberto consome um descritor de arquivo do sistema operacional. Um script de longa execução (ou um loop que abre arquivos sem fechá-los) pode esgotar o limite de descritores e começar a falhar com "Too many open files".

O PHP fecha automaticamente todos os handles ainda abertos quando o script termina, portanto raramente você perde dados em um script curto. Mas ainda assim você deve fechar os handles explicitamente — especialmente em loops e processos de longa execução — para que os recursos sejam liberados o mais cedo possível.

Sintaxe

fclose(resource $stream): bool

• $stream — o ponteiro de arquivo aberto que você deseja fechar.

Parâmetros

A função fclose() aceita um parâmetro obrigatório:

1. $stream: O ponteiro de arquivo que você deseja fechar. Deve ser um recurso válido e aberto retornado por fopen(), fsockopen(), popen() ou uma função semelhante. Passar um recurso inválido ou já fechado dispara um TypeError (PHP 8+) ou um aviso (PHP 7), e a função retorna false.

Valores de Retorno

Retorna true em caso de sucesso ou false em caso de falha.

Exemplos

Exemplo 1: Abrir, escrever e fechar um arquivo

O padrão mais comum é abrir um arquivo, trabalhar com ele e depois fechá-lo. Fechar libera o texto em buffer para o disco:

Escrever em um arquivo e fechar o handle

<?php

$handle = fopen("notes.txt", "w");   // open for writing (creates/empties the file)
fwrite($handle, "Hello, fclose!\n");
fclose($handle);                      // flush + release the handle

echo "File written and closed.";

Saída:

File written and closed.

Exemplo 2: Sempre verificar se o arquivo foi aberto

fopen() retorna false se o arquivo não puder ser aberto (arquivo ausente, sem permissão). Fechar false é um erro, portanto verifique o handle primeiro:

Proteger contra uma abertura com falha

<?php

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

if ($handle === false) {
    echo "Could not open the file.";
} else {
    // ... read from the file ...
    fclose($handle);
    echo "Done.";
}

Exemplo 3: Fechar dentro de um loop

Quando você processa muitos arquivos, feche cada handle assim que terminar para que os descritores não se acumulem:

Fechar cada handle dentro do loop

<?php

$files = ["a.txt", "b.txt", "c.txt"];

foreach ($files as $name) {
    $handle = fopen($name, "r");
    if ($handle !== false) {
        // ... process the file ...
        fclose($handle);   // closed before the next iteration opens another
    }
}

Exemplo 4: Verificar o valor de retorno

Em código onde um fechamento com falha importa (por exemplo, ao escrever em um stream de rede), inspecione o valor de retorno:

Tratar um fechamento com falha

<?php

$handle = fopen("report.txt", "w");
fwrite($handle, "Generated report\n");

if (fclose($handle) === false) {
    echo "Failed to close the file — data may not have been saved.";
} else {
    echo "File saved successfully.";
}

Armadilhas comuns

• Não use um handle após fechá-lo. Assim que fclose() é executado, o recurso é inválido; chamar fread(), fwrite() ou fclose() novamente nele vai falhar.
• Um fclose() para cada fopen(). Fechar o mesmo handle duas vezes dispara um erro na segunda chamada.
• fclose() não exclui o arquivo. Ele apenas libera o ponteiro. Use unlink() para remover um arquivo do disco.
• Fechamento automático ≠ gratuito. Depender do fechamento automático do PHP no final do script é aceitável para scripts pequenos, mas um loop que abre sem fechar pode atingir o limite de descritores de arquivo do SO muito antes de o script terminar.

Funções relacionadas

• fopen() — abre um arquivo e obtém o handle que fclose() posteriormente fecha.
• fwrite() — escreve dados em um handle aberto.
• fread() / fgets() — lê de um handle aberto.
• feof() — testa se você chegou ao final do arquivo.
• PHP File Handling — o panorama geral do trabalho com arquivos.

Conclusão

fclose() fecha um ponteiro de arquivo aberto, liberando quaisquer escritas em buffer e o recurso de sistema subjacente. Embora o PHP feche os handles automaticamente quando um script termina, fechá-los explicitamente — especialmente dentro de loops e scripts de longa execução — evita que seus descritores de arquivo se esgotem e garante que seus dados cheguem ao disco. Combine cada fopen() com um fclose() e proteja-se contra uma abertura com falha antes de ler, escrever ou fechar.

Prática