Signatur
Beschreibung
stat() liest Metadaten einer Datei oder eines Verzeichnisses vom Dateisystem und gibt sie als Array mit 13 numerischen und 13 assoziativen Schlüsseln zurück. Typische Anwendungsfälle sind das Abfragen der Dateigröße, des letzten Änderungszeitpunkts oder der Unix-Zugriffsrechte, ohne die Datei selbst öffnen zu müssen.
Die wichtigsten assoziativen Schlüssel sind: size (Dateigröße in Bytes), mtime (Unix-Timestamp der letzten Änderung), atime (letzter Zugriff), ctime (letzte Inode-Änderung), mode (Dateiberechtigungen als Oktalzahl) sowie uid und gid (Eigentümer-IDs). Auf Windows-Systemen sind einige Felder (z. B. uid, gid, ino) immer 0.
Die Ergebnisse von stat() werden intern von PHP gecacht. Mit clearstatcache() kann dieser Cache geleert werden, was bei häufig geänderten Dateien innerhalb eines Skripts notwendig sein kann. Im Gegensatz zu lstat() folgt stat() symbolischen Links und gibt die Daten der Zieldatei zurück.
Für einzelne Eigenschaften gibt es spezialisierte Funktionen wie filesize(), filemtime() oder fileperms(), die intern ebenfalls gecachte stat()-Daten verwenden. stat() selbst ist nützlich, wenn mehrere Attribute auf einmal benötigt werden.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $filename Pflicht | string | Pfad zur Datei oder zum Verzeichnis, über das Informationen gesammelt werden sollen. Relative und absolute Pfade sowie Stream-Wrapper (z. B. ftp://) werden unterstützt, sofern der Wrapper stat() implementiert. |
Rückgabewert
dev, ino, mode, nlink, uid, gid, rdev, size, atime, mtime, ctime, blksize, blocks. Bei einem Fehler (z. B. Datei nicht vorhanden, keine Leserechte) wird false zurückgegeben und eine E_WARNING ausgelöst.Beispiele
Grundlegende Dateiinformationen ausgeben
<?php
$info = stat('/var/www/html/index.php');
if ($info === false) {
echo 'Datei nicht gefunden oder kein Zugriff.';
} else {
echo 'Dateigröße : ' . $info['size'] . ' Bytes' . PHP_EOL;
echo 'Letzte Änderung: ' . date('d.m.Y H:i:s', $info['mtime']) . PHP_EOL;
echo 'Letzter Zugriff: ' . date('d.m.Y H:i:s', $info['atime']) . PHP_EOL;
echo 'Berechtigungen : ' . decoct($info['mode']) . PHP_EOL;
}Datei nur verarbeiten, wenn sie jünger als 1 Stunde ist
<?php
$file = '/tmp/feed_cache.json';
$info = stat($file);
if ($info !== false && (time() - $info['mtime']) < 3600) {
// Cache ist aktuell, direkt verwenden
$data = json_decode(file_get_contents($file), true);
echo 'Cache verwendet. Alter: ' . (time() - $info['mtime']) . ' Sekunden.' . PHP_EOL;
} else {
// Cache abgelaufen oder Datei existiert nicht
echo 'Cache wird neu aufgebaut ...' . PHP_EOL;
// ... Daten laden und in $file speichern
}Stat-Cache nach Dateioperationen leeren
<?php
$file = '/tmp/testfile.txt';
file_put_contents($file, 'Erster Inhalt');
$before = stat($file);
echo 'Größe vorher: ' . $before['size'] . ' Bytes' . PHP_EOL;
// Datei verändern
file_put_contents($file, 'Zweiter, deutlich längerer Inhalt');
// Ohne clearstatcache() würden gecachte (veraltete) Werte zurückgegeben
clearstatcache(true, $file);
$after = stat($file);
echo 'Größe nachher: ' . $after['size'] . ' Bytes' . PHP_EOL;// Wichtig · Fallstricke
Stat-Cache: PHP cached stat()-Ergebnisse für die Laufzeit eines Skripts. Wenn sich Dateieigenschaften innerhalb desselben Skripts ändern, muss clearstatcache() aufgerufen werden, um veraltete Werte zu vermeiden.
Große Dateien auf 32-Bit-Systemen: Auf 32-Bit-Plattformen kann size bei Dateien > 2 GB einen negativen Wert oder Überlauf liefern. Für solche Szenarien sollte auf 64-Bit-PHP gesetzt oder sprintf('%u', ...) verwendet werden.
Symbolische Links: stat() folgt symbolischen Links und gibt die Informationen der Zieldatei zurück. Um Informationen über den Link selbst zu erhalten, muss lstat() verwendet werden.
Berechtigungen: Das Feld mode enthält neben den Dateirechten auch den Dateityp (z. B. reguläre Datei, Verzeichnis). Die reinen Berechtigungsbits erhält man mit $info['mode'] & 0777.