tempnam()

Introduction

tempnam() creates a temporary file with a unique name and returns the full path to it. Crucially, it doesn't just generate a name — it actually creates the file on disk (empty, with mode 0600), so there is no race where two processes could pick the same name. Use it whenever your script needs scratch space on disk: buffering an upload, generating a report before streaming it, or handing a path to an external command.

This chapter covers the syntax, the return value, where the file actually lands, the gotchas that bite people in production, and how to clean up afterward.

Syntax

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

Return value: the full path to the newly created file (e.g. /tmp/example_aB3xYz), or false on failure.

Creating a temporary file

<?php

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

sys_get_temp_dir() returns the OS temp directory (/tmp on Linux/macOS, the TEMP path on Windows), which is more portable than hard-coding /tmp.

Writing to and reading from the file

tempnam() only gives you a path to an empty file — you still open it to put data in:

<?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);

Because tempnam() does not delete the file for you, always remove it with unlink() once you're finished — otherwise temp files accumulate.

The fallback behavior

If $directory does not exist or is not writable, tempnam() does not fail outright — it silently creates the file in the system temp directory instead. This means the returned path may not be inside the directory you asked for, so never assume the location:

<?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

Always use the returned path for subsequent operations rather than rebuilding it from $directory and $prefix.

tempnam() vs tmpfile()

Both create a unique temporary file, but they serve different needs:

• tempnam() returns a path (string). The file persists until you unlink() it, and you can pass the path to other functions or external programs.
• tmpfile() returns an open file handle, and the file is deleted automatically when the handle is closed or the script ends. Use it when you only need the handle and want automatic cleanup.

Reach for tempnam() when something else needs the file name; reach for tmpfile() when you just need a self-cleaning scratch handle.

Common gotchas

• It creates the file. The file already exists (empty) after the call, so checking file_exists() on the result is always true. To detect failure, compare against false instead.
• Always unlink. Temporary files are not auto-removed. Pair every tempnam() with an unlink(), ideally in a finally block.
• Don't trust the directory. Because of the fallback, the file may not be where you asked. Use the returned path.
• Prefix is truncated. Long prefixes are cut short (3 chars on Windows), so don't rely on the full prefix being present in the name.

Conclusion

tempnam() safely creates a uniquely named, empty temporary file and returns its path. Remember that it creates the file (not just a name), may fall back to the system temp directory, and never cleans up after itself — so always work with the returned path and call unlink() when done. When you only need a self-deleting handle, prefer tmpfile() instead.

Practice