diskfreespace()

Introduction à la fonction PHP diskfreespace()

La fonction diskfreespace() renvoie le nombre d'octets d'espace libre disponible sur le système de fichiers ou la partition disque contenant un répertoire donné. Elle est utile lorsque vous devez vérifier la capacité avant d'écrire des fichiers volumineux, créer des tableaux de bord de surveillance serveur, ou avertir un administrateur que le stockage est presque plein.

diskfreespace() est simplement un alias de disk_free_space() — les deux noms appellent exactement la même implémentation C et se comportent de manière identique. La version avec underscore est le nom canonique dans le manuel PHP ; la version sans underscore existe pour la compatibilité ascendante. Le nouveau code devrait préférer disk_free_space(), mais vous verrez encore diskfreespace() dans les bases de code plus anciennes.

Ce chapitre couvre la syntaxe, l'unique argument qu'elle accepte, ce qu'elle retourne, des exemples exécutables et les pièges courants.

Syntaxe

diskfreespace(string $directory): float|false

La fonction prend un argument obligatoire et retourne l'espace libre sous forme de nombre à virgule flottante d'octets. Un float est utilisé (plutôt qu'un int) car les disques modernes peuvent contenir bien plus d'octets qu'un entier 32 bits ne peut en représenter. En cas d'échec, elle retourne false.

Paramètre

• $directory (string, requis) — Un répertoire sur le système de fichiers que vous souhaitez inspecter (par exemple "/", "C:", ou "." pour le répertoire courant). PHP mesure la partition sur laquelle ce répertoire réside, et non la taille du répertoire lui-même. Le chemin doit être un répertoire ; passer un fichier ordinaire produit un avertissement et retourne false.

Valeur de retour

• En cas de succès : un float — le nombre d'octets libres sur la partition.
• En cas d'échec (le chemin n'existe pas, n'est pas un répertoire, ou n'est pas lisible) : false, plus un E_WARNING.

Exemples

Exemple 1 : Espace libre sur la partition courante

L'appel portable le plus sûr utilise "." (le répertoire courant), qui fonctionne sur tous les systèmes d'exploitation :

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

La sortie est un nombre brut d'octets, comme :

123456789012 bytes free

Exemple 2 : Formater le résultat en taille lisible

Les octets bruts sont difficiles à lire. Cette fonction auxiliaire convertit la valeur en 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

Sortie :

114.98 GB

Exemple 3 : Vérifier un chemin spécifique et gérer les échecs

Vérifiez toujours si la valeur est false avant d'utiliser le résultat, car le chemin peut être invalide :

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

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

Le @ supprime l'avertissement afin que vous puissiez gérer l'erreur avec votre propre message.

Pièges courants

• Elle mesure la partition, pas le dossier. Appeler diskfreespace("/var/www") rapporte l'espace libre sur le disque où réside /var/www, pas la taille utilisée par ce seul dossier.
• Passez un répertoire, pas un fichier. Un chemin de fichier (par exemple "/etc/hosts") retourne false et émet un avertissement.
• Chemins Windows. Utilisez une lettre de lecteur comme "C:" plutôt qu'un chemin de style Unix.
• Espace libre vs. espace utilisable. Sur certains systèmes de fichiers, une portion de l'espace « libre » est réservée à l'utilisateur root, de sorte que le chiffre peut différer légèrement de ce qu'un processus non-root peut réellement utiliser.

Fonctions associées

• disk_free_space() — le nom canonique de cette même fonction.
• disk_total_space() — capacité totale de la partition ; à combiner avec cette fonction pour calculer le pourcentage utilisé.
• filesize() — taille d'un fichier individuel en octets.

Conclusion

diskfreespace() retourne les octets libres sur la partition contenant un répertoire donné et est un alias de disk_free_space(). Utilisez-la pour surveiller le stockage et éviter les écritures qui dépasseraient la capacité du disque, vérifiez toujours si la valeur de retour est false, et associez-la à disk_total_space() lorsque vous avez besoin du pourcentage d'espace restant.

Pratique