stat()

Einführung

Die Funktion stat() gibt ein einzelnes Array mit Low-Level-Metadaten einer Datei zurück: Größe, Berechtigungen, Eigentümer, Inode, Anzahl der Verweise und drei Zeitstempel (Zugriff, Änderung und Inode-Änderung). Sie ist PHPs Wrapper um den C-Systemaufruf stat() und liefert in einem einzigen Aufruf dieselben Informationen, die man sonst aus vielen einzelnen Funktionen wie filesize(), filemtime() und fileperms() zusammensuchen müsste.

Dieser Artikel behandelt die Syntax, die vollständige Bedeutung jedes von stat() zurückgegebenen Wertes, häufige Fallstricke (den Stat-Cache, symbolische Links sowie String- und numerische Indizes) und ausführbare Beispiele.

Syntax

stat(string $filename): array|false

• $filename — der Pfad zur Datei, über die Informationen abgerufen werden sollen.
• Rückgabewert — ein Array mit Datei-Metadaten oder false bei einem Fehler (z. B. wenn die Datei nicht existiert oder nicht lesbar ist). Da die Funktion false zurückgeben kann, sollte das Ergebnis immer vor der Verwendung geprüft werden.

stat() folgt symbolischen Links und gibt Informationen über die Zieldatei zurück. Werden Metadaten über den Link selbst benötigt, verwendet man lstat(). Um eine bereits geöffnete Datei zu untersuchen, steht fstat() zur Verfügung.

Was stat() zurückgibt

Das zurückgegebene Array ist ungewöhnlich: Jeder Wert erscheint zweimal — einmal unter einem numerischen Index und einmal unter einem beschreibenden String-Schlüssel. So sind $info[7] und $info['size'] identische Werte. Diese doppelte Indizierung existiert aus Gründen der Abwärtskompatibilität; für lesbaren Code sollten die benannten Schlüssel bevorzugt werden.

Einige Hinweise:

• mode enthält sowohl den Dateityp als auch die Berechtigungsbits. Um nur die Unix-Berechtigungsbits (z. B. 0644) zu erhalten, wird mit & 0777 maskiert; zur Darstellung in Oktalform wird decoct() verwendet.
• ctime ist der Zeitpunkt der Inode-Änderung (wann Berechtigungen, Eigentümer oder Links zuletzt geändert wurden) — es ist nicht die Erstellungszeit der Datei. Die meisten Unix-Dateisysteme speichern keine Erstellungszeit.
• Die Werte rdev, blksize und blocks sind unter Windows nicht aussagekräftig.

Beispiel: Metadaten einer Datei auslesen

Dieses Beispiel erstellt eine temporäre Datei, führt stat() darauf aus und gibt Größe, Berechtigungen und Änderungszeit aus:

<?php

// Create a small file to inspect.
$path = tempnam(sys_get_temp_dir(), 'demo');
file_put_contents($path, "Hello, stat()!");

$info = stat($path);
if ($info === false) {
    echo "Could not stat the file.";
    exit;
}

echo "Size: {$info['size']} bytes\n";
echo "Permissions: " . decoct($info['mode'] & 0777) . "\n";
echo "Modified: " . date('Y-m-d H:i:s', $info['mtime']) . "\n";

unlink($path); // clean up

Ausgabe (die genauen Berechtigungen und Zeitangaben hängen vom System ab):

Size: 14 bytes
Permissions: 600
Modified: 2026-06-21 12:00:00

Gegen false sollte immer abgesichert werden: Ein fehlender Pfad erzeugt eine Warnung und gibt false zurück, und ein anschließender Index-Zugriff auf false würde sonst einen Fehler auslösen.

Fallstrick: der Stat-Cache

Aus Performancegründen speichert PHP die Ergebnisse von stat() und verwandter Dateifunktionen zwischen. Ändert sich eine Datei während desselben Skriptlaufs und wird erneut abgefragt, können veraltete Daten zurückgegeben werden. Vor dem erneuten Lesen sollte der Cache mit clearstatcache() geleert werden:

<?php

$path = tempnam(sys_get_temp_dir(), 'demo');
file_put_contents($path, "first");
echo stat($path)['size'], "\n"; // 5

file_put_contents($path, "much longer content");
clearstatcache(true, $path);    // refresh cached metadata
echo stat($path)['size'], "\n"; // 19

unlink($path);

stat() im Vergleich zu den spezialisierten Funktionen

Wird nur eine einzelne Information benötigt, sind die dedizierten Funktionen klarer und etwas effizienter:

• Dateigröße → filesize()
• Änderungszeit → filemtime()
• Letzter Zugriffszeitpunkt → fileatime()
• Berechtigungen → fileperms()
• Dateityp → filetype()

stat() empfiehlt sich, wenn mehrere dieser Informationen gleichzeitig benötigt werden, da dabei nur ein einziger Systemaufruf statt vieler erfolgt. Vor dem Abfragen kann es sinnvoll sein, mit is_file() oder file_exists() zu prüfen, ob der Pfad auf eine echte Datei verweist.

Fazit

Die Funktion stat() liefert in einem einzigen Aufruf eine vollständige Low-Level-Momentaufnahme der Metadaten einer Datei. Wichtig dabei: auf false prüfen, die benannten Array-Schlüssel für bessere Lesbarkeit verwenden, mode mit & 0777 für Berechtigungen maskieren und den Stat-Cache leeren, wenn eine Datei während des Skriptlaufs geändert wurde und erneut abgefragt wird. Wird nur ein einzelnes Attribut benötigt, sollte die passende spezialisierte Funktion bevorzugt werden.

Übung