disk_free_space()

Introduction à la fonction PHP disk_free_space()

La fonction disk_free_space() renvoie le nombre d'octets disponibles sur le système de fichiers qui contient un répertoire donné. C'est un outil incontournable pour les administrateurs de serveurs et les développeurs web qui doivent surveiller l'utilisation du disque avant d'écrire des fichiers téléversés, de générer des rapports ou de faire tourner des journaux — afin qu'une application puisse avertir (ou refuser d'écrire) avant que le disque ne soit plein.

Un point clé à comprendre dès le départ : le chemin que vous passez identifie un système de fichiers, et non un simple dossier. Que vous passiez /, /home ou /home/user/uploads, PHP recherche le système de fichiers monté sur lequel ce chemin réside et rapporte l'espace libre pour l'ensemble du point de montage. La valeur est un float car les disques dépassent facilement la plage d'un entier 32 bits.

Ce chapitre couvre la syntaxe, les paramètres, la valeur de retour et des exemples pratiques — notamment comment convertir le nombre brut d'octets en une taille lisible par l'homme et comment calculer le pourcentage d'espace disque utilisé.

Syntaxe

disk_free_space(string $directory): float|false

La fonction prend un seul argument et renvoie le nombre d'octets libres sous forme de float, ou false en cas d'échec (par exemple, lorsque le répertoire n'existe pas). Notez que diskfreespace() est un alias de cette fonction et se comporte de manière identique.

Paramètres

La fonction disk_free_space() prend un paramètre obligatoire :

• $directory — Un chemin string vers n'importe quel fichier ou répertoire sur le système de fichiers que vous souhaitez inspecter. La fonction rapporte l'espace libre du point de montage qui contient ce chemin, et non la taille du répertoire lui-même.

Valeur de retour

En cas de succès, disk_free_space() renvoie l'espace disponible en octets sous forme de float. En cas d'échec, elle renvoie false et émet un avertissement — validez donc toujours le chemin ou vérifiez le résultat avant de vous y fier.

Exemples

Exemple 1 : Obtenir l'espace libre sur un système de fichiers

Passez le répertoire racine pour inspecter le système de fichiers sur lequel le système d'exploitation est installé :

<?php

$bytes = disk_free_space("/");

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

Le nombre exact dépend de votre machine ; sur un disque avec environ 20 Go libres, cela affiche 21474836480.

Exemple 2 : Formater le résultat en taille lisible

Un nombre brut d'octets est difficile à lire. Cette fonction utilitaire convertit les octets dans l'unité la plus proche (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

Sortie :

20 GB
1.5 KB

Exemple 3 : Calculer le pourcentage d'espace disque utilisé

Combinez disk_free_space() avec disk_total_space() pour indiquer le taux de remplissage d'un volume :

<?php

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

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

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

Pour un disque de 100 Go avec 20 Go libres, cela affiche Disk usage: 80%.

Exemple 4 : Protéger une écriture avec une vérification d'erreur

Comme la fonction renvoie false pour un mauvais chemin, vérifiez le résultat avant d'agir :

<?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.";
}

Pièges courants

• Elle mesure le point de montage, pas le dossier. Pour connaître la taille du contenu d'un répertoire, vous devez additionner les tailles des fichiers (voir filesize()) — disk_free_space() ne fait pas cela.
• Gérez false. Un chemin inexistant ou illisible renvoie false et déclenche un avertissement. Validez les entrées avant de les passer.
• Le résultat est un float. Ne le comparez pas avec des entiers en utilisant ===, et ne supposez pas qu'il tient dans un int 32 bits — les grands disques débordent.
• Les restrictions open_basedir peuvent provoquer l'échec de l'appel sur un hébergement mutualisé si le chemin se trouve en dehors des répertoires autorisés.

Conclusion

La fonction disk_free_space() rapporte les octets disponibles sur le système de fichiers contenant un chemin donné — indispensable pour surveiller le stockage et protéger les écritures contre un disque plein. Associez-la à disk_total_space() pour calculer les pourcentages d'utilisation, formatez la valeur brute en octets pour l'affichage, et vérifiez toujours le retour false. Pour en savoir plus sur les fonctions intégrées de PHP, consultez le chapitre fonctions PHP.

Pratique