tmpfile()

Introdução

Quando um script PHP precisa de um local para armazenar dados que só importam durante a duração de uma requisição — um buffer grande demais para manter na memória, um CSV que você está prestes a transmitir para o navegador, saída capturada de um comando externo — você recorre a um arquivo temporário. A função tmpfile() oferece isso com uma única chamada: ela cria um arquivo único no diretório temporário do sistema, abre-o para leitura e escrita, e retorna um identificador de arquivo. O melhor de tudo é que ela faz a limpeza por conta própria.

Este capítulo aborda a sintaxe, o comportamento de limpeza automática que torna o tmpfile() especial, quando usá-lo em vez de tempnam(), e vários exemplos executáveis incluindo alguns erros comuns.

O Que É um Arquivo Temporário?

Um arquivo temporário é um arquivo que o programa usa como espaço de rascunho e não pretende manter. Ele fica no diretório temporário do sistema operacional (/tmp no Linux/macOS, C:\Windows\Temp ou o caminho na variável de ambiente TEMP no Windows). Como muitos processos compartilham esse diretório, os arquivos temporários precisam de nomes únicos para que dois scripts não se sobrescrevam — o tmpfile() cuida dessa unicidade para você.

Entendendo a Função tmpfile()

A função tmpfile() cria um arquivo temporário com nome único no diretório temporário do sistema e o abre para leitura e escrita no modo w+ (o arquivo começa vazio, e você pode tanto escrever nele quanto lê-lo de volta). Ela não recebe parâmetros.

O recurso principal é a limpeza automática. O arquivo temporário é removido quando:

• você fecha o identificador com fclose(), ou
• o script termina e o identificador sai do escopo.

Por causa disso, você quase nunca precisa excluir o arquivo manualmente. A contrapartida é que o tmpfile() não informa o caminho do arquivo — o identificador é a única referência que você obtém. Se você precisar de um nome de arquivo conhecido para passar para outro programa, use tempnam().

Sintaxe da Função tmpfile()

A sintaxe da função tmpfile() é a seguinte:

tmpfile(): resource|false

A função não recebe argumentos e retorna:

• um identificador de arquivo (resource) posicionado no início do arquivo vazio em caso de sucesso, ou
• false em caso de falha — por exemplo, quando o diretório temporário não é gravável.

Sempre verifique o valor de retorno antes de usar o identificador, pois passar false para funções como fwrite() dispara um TypeError no PHP 8+.

Exemplos de Uso do tmpfile()

Exemplo 1: Escrever, Ler de Volta e Limpeza Automática

O padrão mais comum: abrir um arquivo temporário, escrever nele, rebobinar o ponteiro e lê-lo de volta. Observe a chamada rewind() — após escrever, o ponteiro interno fica no final dos dados, então sem rebobinar o fread() retornaria uma string vazia.

<?php

$handle = tmpfile();
if ($handle === false) {
    die('Failed to create temporary file');
}

fwrite($handle, 'Example data');
rewind($handle);                  // move pointer back to the beginning
echo fread($handle, 1024);        // read up to 1024 bytes
fclose($handle);                  // closing also deletes the file

Saída:

Example data

O arquivo é removido no momento em que fclose() é executado, então não há nada para limpar manualmente.

Exemplo 2: Encontrar o Caminho Real do Arquivo Temporário

Embora o tmpfile() oculte o nome do arquivo, você pode recuperá-lo por meio dos metadados do stream com stream_get_meta_data(). Isso é útil para registro ou depuração — por exemplo, para confirmar que o arquivo realmente desaparece.

<?php

$handle = tmpfile();
$meta   = stream_get_meta_data($handle);
$path   = $meta['uri'];

echo 'Temp file exists before close: ';
echo file_exists($path) ? 'yes' : 'no';
echo "\n";

fclose($handle);

echo 'Temp file exists after close:  ';
echo file_exists($path) ? 'yes' : 'no';
echo "\n";

Saída:

Temp file exists before close: yes
Temp file exists after close:  no

Exemplo 3: Armazenando Linhas CSV em Buffer Antes de Enviar

Um caso de uso realista: construir um CSV em um arquivo temporário usando fputcsv(), depois ler tudo de volta para retornar ou transmitir. Isso mantém dados grandes fora da memória enquanto ainda permite montar linha por linha.

<?php

$rows = [
    ['Name', 'Role'],
    ['Ada', 'Engineer'],
    ['Linus', 'Maintainer'],
];

$handle = tmpfile();
foreach ($rows as $row) {
    fputcsv($handle, $row);
}

rewind($handle);
echo stream_get_contents($handle);   // read everything from the pointer to EOF
fclose($handle);

Saída:

Name,Role
Ada,Engineer
Linus,Maintainer

tmpfile() vs tempnam()

Ambas criam arquivos temporários, mas resolvem problemas diferentes:

Regra geral: use tmpfile() para dados de rascunho autocontidos dentro de um script; use tempnam() quando precisar de um arquivo nomeado para passar a outro processo ou para manter após a requisição.

Armadilhas Comuns

• Esquecer de usar rewind(). Após escrever, o ponteiro está no final. Ler sem rebobinar não retorna nada.
• Assumir um valor de retorno. Em um diretório temporário somente leitura, tmpfile() retorna false; sempre verifique isso.
• Esperar que o arquivo persista. Uma vez fechado o identificador, o arquivo se vai — copie os dados (com fopen() para um caminho permanente, file_put_contents(), etc.) se precisar mantê-los.

Conclusão

A função tmpfile() é a maneira mais simples de obter um arquivo de rascunho privado e com limpeza automática em PHP. Ela entrega um identificador de leitura e escrita, coloca o arquivo com segurança no diretório temporário do sistema e o exclui no momento em que você fecha o identificador ou o script termina — sem necessidade de manutenção manual. Recorra a ela sempre que precisar de armazenamento de curta duração e não se importar com o nome do arquivo; recorra a tempnam() quando precisar do nome.

Prática