tempnam()

Introdução

tempnam() cria um arquivo temporário com um nome único e retorna o caminho completo para ele. De forma importante, ela não apenas gera um nome — ela cria o arquivo no disco (vazio, com permissão 0600), eliminando a condição de corrida em que dois processos poderiam escolher o mesmo nome. Use-a sempre que seu script precisar de espaço temporário em disco: armazenar em buffer um upload, gerar um relatório antes de transmiti-lo ou passar um caminho para um comando externo.

Este capítulo aborda a sintaxe, o valor de retorno, onde o arquivo é criado de fato, os problemas que surgem em produção e como fazer a limpeza depois.

Sintaxe

tempnam(string $directory, string $prefix): string|false

Valor de retorno: o caminho completo para o arquivo recém-criado (por exemplo, /tmp/example_aB3xYz), ou false em caso de falha.

Criando um arquivo temporário

<?php

$tempFile = tempnam(sys_get_temp_dir(), 'example_');
echo $tempFile;
// e.g. /tmp/example_8gKq2P

sys_get_temp_dir() retorna o diretório temporário do sistema operacional (/tmp no Linux/macOS, o caminho TEMP no Windows), o que é mais portável do que usar /tmp diretamente no código.

Escrevendo e lendo o arquivo

tempnam() apenas fornece um caminho para um arquivo vazio — você ainda precisa abri-lo para inserir dados:

<?php

$tempFile = tempnam(sys_get_temp_dir(), 'report_');

// Write some data
file_put_contents($tempFile, "Line 1\nLine 2\n");

// Read it back
echo file_get_contents($tempFile);
// Line 1
// Line 2

// Clean up when you're done
unlink($tempFile);

Como tempnam() não exclui o arquivo por conta própria, sempre o remova com unlink() quando terminar — caso contrário, os arquivos temporários se acumulam.

O comportamento de fallback

Se $directory não existir ou não for gravável, tempnam() não falha diretamente — ela cria silenciosamente o arquivo no diretório temporário do sistema. Isso significa que o caminho retornado pode não estar dentro do diretório solicitado, portanto nunca assuma a localização:

<?php

// /no/such/dir doesn't exist
$tempFile = tempnam('/no/such/dir', 'data_');

// File is created in sys_get_temp_dir(), not /no/such/dir
echo dirname($tempFile) === sys_get_temp_dir() ? 'fell back' : $tempFile;
// fell back

Sempre use o caminho retornado para operações subsequentes, em vez de reconstruí-lo a partir de $directory e $prefix.

tempnam() vs tmpfile()

Ambas criam um arquivo temporário único, mas servem a necessidades diferentes:

• tempnam() retorna um caminho (string). O arquivo persiste até que você o remova com unlink(), e você pode passar o caminho para outras funções ou programas externos.
• tmpfile() retorna um identificador de arquivo aberto, e o arquivo é excluído automaticamente quando o identificador é fechado ou o script termina. Use-a quando precisar apenas do identificador e quiser limpeza automática.

Opte por tempnam() quando algo mais precisar do nome do arquivo; opte por tmpfile() quando precisar apenas de um identificador temporário com autolimpeza.

Problemas comuns

• Ela cria o arquivo. O arquivo já existe (vazio) após a chamada, portanto verificar file_exists() no resultado sempre retornará verdadeiro. Para detectar falhas, compare com false.
• Sempre use unlink. Arquivos temporários não são removidos automaticamente. Combine cada tempnam() com um unlink(), idealmente em um bloco finally.
• Não confie no diretório. Por causa do fallback, o arquivo pode não estar onde você pediu. Use o caminho retornado.
• O prefixo é truncado. Prefixos longos são cortados (3 caracteres no Windows), portanto não conte com o prefixo completo presente no nome.

Conclusão

tempnam() cria com segurança um arquivo temporário vazio com nome único e retorna seu caminho. Lembre-se de que ela cria o arquivo (não apenas um nome), pode usar o diretório temporário do sistema como alternativa e nunca faz a limpeza sozinha — portanto sempre trabalhe com o caminho retornado e chame unlink() quando terminar. Quando precisar apenas de um identificador com autodeleção, prefira tmpfile().

Prática