disk_free_space()

Einführung in die PHP-Funktion disk_free_space()

Die Funktion disk_free_space() gibt die Anzahl der verfügbaren Bytes auf dem Dateisystem zurück, das ein angegebenes Verzeichnis enthält. Sie ist ein unverzichtbares Werkzeug für Serveradministratoren und Webentwickler, die den Festplattenverbrauch überwachen müssen, bevor sie Uploads schreiben, Berichte erstellen oder Logs rotieren – damit eine Anwendung warnen (oder das Schreiben verweigern) kann, bevor die Festplatte voll ist.

Ein wichtiger Punkt vorab: Der übergebene Pfad identifiziert ein Dateisystem, nicht einen einzelnen Ordner. Egal ob Sie /, /home oder /home/user/uploads übergeben – PHP ermittelt das eingehängte Dateisystem, auf dem sich dieser Pfad befindet, und gibt den freien Speicherplatz für den gesamten Mount zurück. Der Rückgabewert ist ein float, da Festplatten den Bereich eines 32-Bit-Integers leicht überschreiten.

Dieses Kapitel behandelt die Syntax, Parameter, den Rückgabewert und praktische Beispiele – einschließlich der Umrechnung des rohen Bytewerts in eine lesbare Größe und der Berechnung des prozentualen Festplattenverbrauchs.

Syntax

disk_free_space(string $directory): float|false

Die Funktion nimmt ein einzelnes Argument und gibt die Anzahl der freien Bytes als float zurück oder false bei einem Fehler (zum Beispiel wenn das Verzeichnis nicht existiert). Beachten Sie, dass diskfreespace() ein Alias dieser Funktion ist und sich identisch verhält.

Parameter

Die Funktion disk_free_space() nimmt einen erforderlichen Parameter:

• $directory — Ein string-Pfad zu einer beliebigen Datei oder einem Verzeichnis auf dem zu untersuchenden Dateisystem. Die Funktion gibt den freien Speicherplatz des Mounts zurück, der diesen Pfad enthält, nicht die Größe des Verzeichnisses selbst.

Rückgabewert

Bei Erfolg gibt disk_free_space() den verfügbaren Speicherplatz in Bytes als float zurück. Bei einem Fehler gibt sie false zurück und erzeugt eine Warnung. Validieren Sie daher immer den Pfad oder prüfen Sie das Ergebnis, bevor Sie sich darauf verlassen.

Beispiele

Beispiel 1: Freien Speicherplatz auf einem Dateisystem ermitteln

Übergeben Sie das Wurzelverzeichnis, um das Dateisystem zu untersuchen, auf dem das Betriebssystem installiert ist:

<?php

$bytes = disk_free_space("/");

echo $bytes; // e.g. 21474836480 (raw bytes)

Die genaue Zahl hängt von Ihrem System ab; auf einer Festplatte mit etwa 20 GB freiem Speicher wird 21474836480 ausgegeben.

Beispiel 2: Ergebnis als lesbare Größe formatieren

Ein roher Bytewert ist schwer zu lesen. Diese Hilfsfunktion konvertiert Bytes in die nächstgelegene Einheit (KB, MB, GB, …):

<?php

function formatBytes(float $bytes, int $precision = 2): string
{
    $units = ['B', 'KB', 'MB', 'GB', 'TB'];

    $pow = $bytes > 0 ? floor(log($bytes, 1024)) : 0;
    $pow = min($pow, count($units) - 1);

    $bytes /= 1024 ** $pow;

    return round($bytes, $precision) . ' ' . $units[$pow];
}

echo formatBytes(21474836480); // 20 GB
echo "\n";
echo formatBytes(1536);        // 1.5 KB

Ausgabe:

20 GB
1.5 KB

Beispiel 3: Prozentualen Festplattenverbrauch berechnen

Kombinieren Sie disk_free_space() mit disk_total_space(), um zu ermitteln, wie voll ein Datenträger ist:

<?php

$total = disk_total_space("/");
$free  = disk_free_space("/");
$used  = $total - $free;

$percentUsed = round(($used / $total) * 100, 1);

echo "Disk usage: {$percentUsed}%";

Bei einer 100 GB-Festplatte mit 20 GB freiem Speicher wird Disk usage: 80% ausgegeben.

Beispiel 4: Schreibvorgang mit Fehlerprüfung absichern

Da die Funktion bei einem ungültigen Pfad false zurückgibt, prüfen Sie das Ergebnis, bevor Sie damit arbeiten:

<?php

$path = "/var/www/uploads";
$free = disk_free_space($path);

if ($free === false) {
    echo "Could not read free space for {$path}";
} elseif ($free < 100 * 1024 * 1024) { // less than 100 MB
    echo "Warning: low disk space!";
} else {
    echo "Enough space to continue.";
}

Häufige Fallstricke

• Es wird der Mount gemessen, nicht der Ordner. Um die Größe des Inhalts eines Verzeichnisses zu ermitteln, müssen Sie die Dateigrößen addieren (siehe filesize()) — disk_free_space() kann das nicht.
• false behandeln. Ein nicht vorhandener oder nicht lesbarer Pfad gibt false zurück und löst eine Warnung aus. Validieren Sie die Eingabe, bevor Sie sie übergeben.
• Das Ergebnis ist ein float. Vergleichen Sie es nicht mit Integers über ===, und gehen Sie nicht davon aus, dass es in einen 32-Bit-int passt — große Festplatten laufen über.
• open_basedir-Einschränkungen können dazu führen, dass der Aufruf auf Shared-Hosting-Umgebungen fehlschlägt, wenn der Pfad außerhalb der erlaubten Verzeichnisse liegt.

Fazit

Die Funktion disk_free_space() gibt die verfügbaren Bytes auf dem Dateisystem zurück, das einen angegebenen Pfad enthält – unverzichtbar für die Speicherüberwachung und die Absicherung von Schreibvorgängen gegen eine volle Festplatte. Kombinieren Sie sie mit disk_total_space(), um Verbrauchsprozentsätze zu berechnen, formatieren Sie den rohen Bytewert für die Anzeige und prüfen Sie stets auf einen false-Rückgabewert. Weitere Informationen zu PHP-Builtin-Funktionen finden Sie im Kapitel PHP-Funktionen.

Übungen