touch()

Introduction

In PHP, the touch() function is used to set the modification and access time of a file. It is a useful function for working with files in your PHP scripts. In this article, we will cover everything you need to know about the touch() function, including its syntax, parameters, and examples of how it can be used.

Understanding the touch() Function

The touch() function updates the modification time (mtime) and access time (atime) of a file. It accepts three parameters:

• $filename — the path to the file.
• $mtime (optional) — the modification timestamp as a Unix time. If omitted, the current time (time()) is used.
• $atime (optional) — the access timestamp as a Unix time. If omitted, the value passed to $mtime is used (not necessarily the current time).

If the specified file does not exist, touch() creates an empty file at that path. This makes it the standard PHP equivalent of the Unix touch command.

You typically reach for touch() when you want to:

• Create an empty placeholder or lock file.
• "Bump" a file's mtime so cache-invalidation tools (or make-style build checks) treat it as freshly changed.
• Set a known timestamp on a file for testing or for systems that compare modification times.

Syntax of the touch() Function

The syntax of the touch() function is as follows:

touch(string $filename, ?int $mtime = null, ?int $atime = null): bool

Here, $filename is the path to the file, $mtime is the modification timestamp in Unix format, and $atime is the access timestamp. Both timestamps are optional. The function returns true on success or false on failure.

A timestamp in PHP is simply the number of seconds since the Unix epoch (Jan 1, 1970). Use time() for "now", strtotime() to parse a date string, or arithmetic such as time() - 3600 for "one hour ago".

Examples of Using touch()

Let's take a look at an example of how the touch() function can be used in PHP.

Example 1: Updating the Modification and Access Time of a File

if (touch('example.txt', time())) {
    echo "File timestamps updated successfully.";
} else {
    echo "Failed to update file timestamps. Check permissions or file path.";
}

This example updates the modification and access time of the example.txt file to the current time. The if statement checks the boolean return value to handle potential errors, such as missing files or insufficient permissions.

Example 2: Setting Both Modification and Access Times Explicitly

$mtime = time() - 3600; // 1 hour ago
$atime = time() - 1800; // 30 minutes ago

if (touch('example.txt', $mtime, $atime)) {
    echo "Both timestamps updated successfully.";
} else {
    echo "Failed to update timestamps.";
}

This example demonstrates how to pass both $mtime and $atime parameters to set different values for modification and access times.

Example 3: Creating a Placeholder File

Because touch() creates the file when it is missing, it is a concise way to make an empty file without opening a stream:

$path = 'cache/.gitkeep';

if (!file_exists($path)) {
    touch($path);
    echo "Placeholder created.";
} else {
    echo "Placeholder already exists.";
}

After calling touch(), you can read back the new modification time with filemtime() to confirm the change:

$timestamp = mktime(0, 0, 0, 1, 1, 2030); // Jan 1, 2030 (in the default timezone)
touch('example.txt', $timestamp);
echo filemtime('example.txt') === $timestamp ? 'mtime set' : 'mismatch';

Note: Ensure the PHP process has write permissions for the target directory. If the file does not exist, touch() will create it with default permissions (subject to the system umask). Setting an mtime in the future is allowed and is sometimes used to force cache rebuilds.

Conclusion

The touch() function provides a straightforward way to manage file timestamps in PHP. Whether you need to update access times for caching systems, track file activity, or create placeholder files, this function integrates seamlessly into your file-handling workflows. We hope this guide has clarified how to use touch() effectively in your projects.

Related Functions

• filemtime() — read a file's last modification time.
• file_exists() — check whether a file or directory exists before touching it.
• fopen() — open or create a file when you also need to write content.
• unlink() — delete a file.
• date() — format the Unix timestamps that touch() works with.

Practice