filemtime()

Die Funktion filemtime() ist eine eingebaute PHP-Funktion, die den Zeitpunkt zurückgibt, zu dem der Inhalt einer Datei zuletzt geändert wurde – als Unix-Timestamp. Sie gehört zu PHPs Dateisystem-Inspektionsfunktionen und wird häufig für Cache-Invalidierung, „Zuletzt aktualisiert"-Beschriftungen und die Erkennung von Dateiänderungen seit dem letzten Lesen verwendet.

Dieses Kapitel behandelt die Syntax, den Rückgabewert, den Unterschied zwischen filemtime() und den verwandten Funktionen filectime() / fileatime(), die Formatierung des Ergebnisses für Menschen, die Fehlerbehandlung sowie den Caching-Fallstrick, über den fast jeder stolpert.

Syntax

filemtime(string $filename): int|false

• $filename — Pfad zur zu untersuchenden Datei (oder zum Verzeichnis).
• Rückgabewert — die Änderungszeit als Unix-Timestamp (Sekunden seit dem 1. Januar 1970 UTC) bei Erfolg oder false bei Fehler.

Die „Änderungszeit" (mtime) ändert sich immer dann, wenn der Inhalt der Datei geschrieben wird. Sie ändert sich nicht, wenn die Datei lediglich gelesen wird, und auch nicht, wenn sich nur die Metadaten (Berechtigungen, Eigentümer) ändern – das ist die Inode-Änderungszeit, die von filectime() gemeldet wird.

Ein einfaches Beispiel

Da ein Unix-Timestamp nur eine große Ganzzahl ist, wird er typischerweise an date() übergeben, um einen lesbaren String zu erzeugen:

<?php

$filename = __FILE__; // inspect this script itself

$timestamp = filemtime($filename);
$readable  = date('F d Y H:i:s', $timestamp);

echo "The file was last modified on $readable";

__FILE__ ist eine magische Konstante, die immer auf das aktuelle Skript zeigt, sodass dieses Snippet ausgeführt werden kann, ohne dass Sie eine separate Datei erstellen müssen. filemtime() gibt den Timestamp zurück, und date() formatiert ihn (hier: vollständiger Monatsname, Tag, Jahr und anschließend die 24-Stunden-Zeit).

Fehler immer behandeln

filemtime() gibt false zurück, wenn die Datei nicht existiert oder nicht gelesen werden kann, und gibt außerdem eine Warnung aus. Da false lose gleich 0 ist, sollten Sie das rohe Ergebnis niemals direkt an date() übergeben – prüfen Sie es zuerst, idealerweise nachdem Sie die Existenz der Datei mit file_exists() bestätigt haben:

<?php

$filename = 'does-not-exist.txt';

if (!file_exists($filename)) {
    echo "File not found.";
} else {
    $timestamp = filemtime($filename);

    if ($timestamp === false) {
        echo "Could not read the modification time.";
    } else {
        echo "Last modified: " . date('Y-m-d H:i:s', $timestamp);
    }
}

Verwenden Sie den strikten Vergleich === false: Ein legitimer Timestamp ist niemals false, aber == false würde auch den (in der Praxis unmöglichen) Timestamp 0 abfangen.

mtime vs. ctime vs. atime

PHP stellt drei verschiedene Datei-Timestamps bereit. Zu wissen, welchen man verwenden soll, verhindert schwer zu findende Fehler:

Für „zeige mir, wann dies zuletzt bearbeitet wurde", möchten Sie fast immer filemtime().

Der Caching-Fallstrick: clearstatcache()

PHP speichert die Ergebnisse von Dateisystemfunktionen wie filemtime() für die Dauer einer Anfrage zwischen. Wenn Sie eine Datei ändern und dann im selben Skript erneut filemtime() aufrufen, erhalten Sie möglicherweise den veralteten Wert. Rufen Sie clearstatcache() auf, um eine neue Abfrage zu erzwingen:

<?php

$filename = tempnam(sys_get_temp_dir(), 'demo');

file_put_contents($filename, 'first write');
$first = filemtime($filename);

sleep(1);
touch($filename);          // bump the mtime

clearstatcache();          // without this, you may still see $first
$second = filemtime($filename);

echo $second > $first ? "mtime updated\n" : "mtime unchanged (cached)\n";

unlink($filename);

Hier aktualisiert touch() die Änderungszeit, und clearstatcache() stellt sicher, dass das zweite filemtime() dies widerspiegelt.

Ein praktisches Beispiel: Cache Busting

Ein häufiger Einsatz in der Praxis ist das Anhängen der mtime einer Datei an eine Asset-URL, damit Browser sie nur dann erneut herunterladen, wenn sich die Datei tatsächlich geändert hat:

<?php

$cssPath = __FILE__; // pretend this is 'styles.css'
$version = filemtime($cssPath);

echo "/assets/styles.css?v=$version";

Jedes Mal, wenn das CSS bearbeitet wird, ändert sich $version und bricht den Browser-Cache automatisch auf.

Fazit

filemtime() meldet, wann der Inhalt einer Datei zuletzt geändert wurde, als Unix-Timestamp, und gibt false bei Fehler zurück. Kombinieren Sie es mit date(), um das Ergebnis zu formatieren, prüfen Sie auf false, denken Sie an clearstatcache(), wenn Sie eine soeben geänderte Datei erneut lesen, und greifen Sie auf filectime() oder fileatime() zurück, wenn Sie stattdessen die Änderungs- oder Zugriffszeit benötigen. Für eine vollständige Sammlung von Dateistatistiken in einem einzigen Aufruf, siehe stat().

Übung