Signatur
Beschreibung
touch() aktualisiert den Zeitstempel für die letzte Modifikation (mtime) und den letzten Zugriff (atime) einer Datei auf den angegebenen Unix-Timestamp. Werden die optionalen Zeitparameter weggelassen, wird die aktuelle Systemzeit verwendet.
Existiert die angegebene Datei noch nicht, legt PHP sie als leere Datei an – sofern das Verzeichnis beschreibbar ist. Dieses Verhalten macht touch() zu einem einfachen Mittel, um sogenannte Flag-Dateien oder Lock-Dateien ohne zusätzlichen Schreibvorgang zu erzeugen.
Typische Anwendungsfälle sind: Caching-Mechanismen, bei denen die Aktualität einer Datei über ihren Zeitstempel geprüft wird, das Invalidieren von Caches durch gezieltes Vorstellen des Zeitstempels sowie das Erstellen von Marker-Dateien in Deployment-Prozessen.
Nach dem Aufruf von touch() sollte der interne Datei-Stat-Cache mit clearstatcache() geleert werden, damit nachfolgende Aufrufe wie filemtime() den neuen Zeitstempel liefern.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $filename Pflicht | string | Pfad zur Datei, deren Zeitstempel gesetzt werden soll. Existiert die Datei nicht, wird sie angelegt. | |
| $mtime | int|null | null | Gewünschter Modifikations-Timestamp als Unix-Timestamp. Wird null übergeben oder der Parameter weggelassen, wird die aktuelle Zeit (time()) verwendet. |
| $atime | int|null | null | Gewünschter Zugriffs-Timestamp als Unix-Timestamp. Wird null übergeben, wird der Wert von mtime (bzw. die aktuelle Zeit) verwendet. |
Rückgabewert
true bei Erfolg zurück, false bei einem Fehler (z. B. fehlende Schreibrechte oder ungültiger Pfad). Im Fehlerfall wird außerdem eine E_WARNING-Meldung ausgegeben.Beispiele
Leere Datei anlegen oder Zeitstempel aktualisieren
<?php
$file = '/tmp/marker.txt';
if (touch($file)) {
echo 'Zeitstempel erfolgreich gesetzt: ' . date('Y-m-d H:i:s', filemtime($file));
} else {
echo 'Fehler beim Setzen des Zeitstempels.';
}Modifikationszeit auf einen bestimmten Zeitpunkt setzen
<?php
$file = '/tmp/report.log';
// Zeitstempel auf gestern um 08:00 Uhr setzen
$gestern = mktime(8, 0, 0, date('n'), date('j') - 1, date('Y'));
if (touch($file, $gestern)) {
clearstatcache();
echo 'Neue mtime: ' . date('Y-m-d H:i:s', filemtime($file));
} else {
echo 'Konnte Zeitstempel nicht setzen.';
}Flag-Datei als Cache-Invalidierungs-Marker
<?php
$cacheFlag = '/tmp/cache_invalidate.flag';
// Flag setzen, um Cache-Rebuild auszulösen
touch($cacheFlag);
// An anderer Stelle im Code prüfen, ob Cache veraltet ist
$cacheFile = '/tmp/my_cache.dat';
if (!file_exists($cacheFile) || filemtime($cacheFlag) > filemtime($cacheFile)) {
echo 'Cache muss neu aufgebaut werden.';
} else {
echo 'Cache ist aktuell.';
}// Wichtig · Fallstricke
Betriebssystem-Unterschiede: Auf einigen Systemen (insbesondere Windows und einigen NFS-Mounts) wird der Zugriffs-Timestamp (atime) nicht zuverlässig unterstützt oder kann deaktiviert sein (noatime-Mount-Option). touch() gibt in solchen Fällen dennoch true zurück.
Stat-Cache: PHP cached intern Datei-Metadaten. Nach einem touch()-Aufruf sollte clearstatcache() aufgerufen werden, damit filemtime(), fileatime() und ähnliche Funktionen den aktualisierten Wert liefern.
Rechte: Der PHP-Prozess benötigt Schreibrechte auf die Datei (bzw. das Verzeichnis, falls die Datei neu angelegt werden soll). Bei unzureichenden Rechten schlägt touch() mit false und einem E_WARNING fehl.