diskfreespace()

Einführung in die PHP-Funktion diskfreespace()

Die Funktion diskfreespace() gibt die Anzahl der freien Bytes auf dem Dateisystem oder der Festplattenpartition zurück, die ein bestimmtes Verzeichnis enthält. Sie ist nützlich, wenn Sie die Kapazität prüfen möchten, bevor Sie große Dateien schreiben, Server-Monitoring-Dashboards erstellen oder einen Administrator warnen müssen, dass der Speicherplatz knapp wird.

diskfreespace() ist lediglich ein Alias von disk_free_space() — beide Namen rufen dieselbe C-Implementierung auf und verhalten sich identisch. Die Version mit Unterstrich ist der kanonische Name im PHP-Handbuch; die Version ohne Unterstrich existiert aus Gründen der Abwärtskompatibilität. Neuer Code sollte disk_free_space() bevorzugen, aber diskfreespace() ist in älteren Codebasen weiterhin zu finden.

Dieses Kapitel behandelt die Syntax, das einzelne Argument, das die Funktion entgegennimmt, was sie zurückgibt, ausführbare Beispiele und häufige Fallstricke.

Syntax

diskfreespace(string $directory): float|false

Die Funktion nimmt ein erforderliches Argument entgegen und gibt den freien Speicherplatz als Gleitkommazahl in Bytes zurück. Es wird ein float verwendet (anstelle eines int), da moderne Festplatten weit mehr Bytes speichern können, als ein 32-Bit-Integer darstellen kann. Bei einem Fehler gibt sie false zurück.

Parameter

• $directory (string, erforderlich) — Ein Verzeichnis auf dem Dateisystem, das Sie untersuchen möchten (zum Beispiel "/", "C:" oder "." für das aktuelle Verzeichnis). PHP misst die Partition, auf der sich dieses Verzeichnis befindet, nicht die Größe des Verzeichnisses selbst. Der Pfad muss ein Verzeichnis sein; die Übergabe einer regulären Datei erzeugt eine Warnung und gibt false zurück.

Rückgabewert

• Bei Erfolg: ein float — die Anzahl der freien Bytes auf der Partition.
• Bei Fehler (Pfad existiert nicht, ist kein Verzeichnis oder ist nicht lesbar): false, zusammen mit einer E_WARNING.

Beispiele

Beispiel 1: Freier Speicherplatz auf der aktuellen Partition

Der sicherste portable Aufruf verwendet "." (das aktuelle Verzeichnis), der auf jedem Betriebssystem funktioniert:

<?php
$bytes = diskfreespace(".");
echo $bytes, " bytes free\n";

Die Ausgabe ist eine rohe Byte-Anzahl, zum Beispiel:

123456789012 bytes free

Beispiel 2: Das Ergebnis als lesbare Größe formatieren

Rohe Bytes sind schwer zu lesen. Dieser Helfer konvertiert den Wert in KB / MB / GB / TB:

<?php
function humanSize(float $bytes): string
{
    $units = ['B', 'KB', 'MB', 'GB', 'TB'];
    $i = 0;
    while ($bytes >= 1024 && $i < count($units) - 1) {
        $bytes /= 1024;
        $i++;
    }
    return round($bytes, 2) . ' ' . $units[$i];
}

echo humanSize(123456789012); // 114.98 GB

Ausgabe:

114.98 GB

Beispiel 3: Einen bestimmten Pfad prüfen und Fehler behandeln

Prüfen Sie immer auf false, bevor Sie das Ergebnis verwenden, da der Pfad ungültig sein kann:

<?php
$path = "/no/such/directory";
$free = @diskfreespace($path);

if ($free === false) {
    echo "Could not read free space for $path";
} else {
    echo "Free: $free bytes";
}

Das @ unterdrückt die Warnung, sodass Sie den Fehler mit einer eigenen Meldung behandeln können.

Häufige Fallstricke

• Es wird die Partition gemessen, nicht der Ordner. Der Aufruf diskfreespace("/var/www") gibt den freien Speicherplatz auf der Festplatte zurück, auf der /var/www liegt, nicht wie viel dieser einzelne Ordner belegt.
• Übergeben Sie ein Verzeichnis, keine Datei. Ein Dateipfad (z. B. "/etc/hosts") gibt false zurück und erzeugt eine Warnung.
• Windows-Pfade. Verwenden Sie einen Laufwerksbuchstaben wie "C:" anstelle eines Unix-artigen Pfades.
• Freier vs. nutzbarer Speicherplatz. Auf manchen Dateisystemen ist ein Teil des „freien" Speicherplatzes für den Root-Benutzer reserviert, sodass der Wert leicht von dem abweichen kann, was ein Nicht-Root-Prozess tatsächlich nutzen kann.

Verwandte Funktionen

• disk_free_space() — der kanonische Name für diese Funktion.
• disk_total_space() — Gesamtkapazität der Partition; kombinieren Sie diese Funktion mit der obigen, um den prozentualen Verbrauch zu berechnen.
• filesize() — Größe einer einzelnen Datei in Bytes.

Fazit

diskfreespace() gibt die freien Bytes auf der Partition zurück, die ein bestimmtes Verzeichnis enthält, und ist ein Alias von disk_free_space(). Verwenden Sie sie, um den Speicher zu überwachen und Schreibvorgänge zu verhindern, die die Festplatte füllen würden, prüfen Sie immer auf einen false-Rückgabewert, und kombinieren Sie sie mit disk_total_space(), wenn Sie den prozentualen verbleibenden Speicherplatz benötigen.

Übungen