Que représente la valeur de retour de la fonction diskfreespace ()? Analyse complète du sens et de l'unité

gitbox 2025-09-19

: diskfreespace () (alias disk_free_space () ) renvoie le nombre d'octets disponibles pour le processus PHP actuel sur le système / partition de fichiers spécifié . L'unité de valeur de retour est des octets , notez qu'il représente généralement l'espace "disponible pour le processus de fonctionnement" plutôt que par les octets libres totaux absolus sur le disque (sur UNIX, il sera affecté par des blocs et des autorisations réservés; il peut également rencontrer des problèmes de débordement entiers sur PHP 32 bits).

Les détails importants sont expliqués ci-dessous et des utilisations courantes sont données.

1. Type de valeur de base et de valeur de retour

 <span><span><span class="hljs-variable">$free</span></span><span> = </span><span><span class="hljs-title function_ invoke__">diskfreespace</span></span><span>(</span><span><span class="hljs-string">'/'</span></span><span>); </span><span><span class="hljs-comment">// ou disk_free_space('/path/to/dir');</span></span><span>
</span><span><span class="hljs-keyword">if</span></span><span> (</span><span><span class="hljs-variable">$free</span></span><span> === </span><span><span class="hljs-literal">false</span></span><span>) {
    </span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"Échec de l&#39;obtention"</span></span><span>;
} </span><span><span class="hljs-keyword">else</span></span><span> {
    </span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"Nombre d&#39;octets disponibles： <span class="hljs-subst">$free</span></span></span><span>\n";
}
</span></span>

Unité de valeur de retour : octets.
Types de retour possibles : généralement un entier (int, 64 bits) sur PHP moderne (64 bits), peut être un numéro de point flottant ou un débordement dans certains environnements ou des environnements PHP / 32 bits plus anciens. La fonction renvoie False en échec et émet un avertissement.
Paramètres : passez dans le chemin du fichier ou le point de montage (par exemple, c: \ , / var , / mnt / share ), et ne peut pas passer directement dans HTTP / FTP et d'autres URL (nécessite un chemin local ou monté).

2. "Disponible" n'est pas toujours égal "absolument inactif"

Le résultat de diskfreespace () est généralement équivalent au champ "disponible" d'un appel système tel que STATVFS ou Windows d'Unix, qui représente le nombre d'octets disponibles pour l'utilisateur actuel (ou le processus de course). donc:

Sur Unix / Linux, le système de fichiers se réserve généralement une partie du bloc (comme 5%) pour la racine. Les utilisateurs non racinaires ne peuvent pas voir cette pièce et la valeur de retour ne contiendra pas l'espace réservé.
Si PHP est exécuté en tant qu'utilisateur non privilégié, la valeur de retour reflète l'espace que l'utilisateur peut écrire, plutôt que tout l'espace libre que le superutilisateur peut utiliser.
Pour les supports réseau (NFS, SMB) ou les environnements de machine à conteneur / virtuel, la valeur de retour sera également affectée par les options de montage et les restrictions de conteneurs (quota, CGROUP, etc.).

Par conséquent - pour déterminer si le disque est "vraiment" gratuit, vous devez comprendre les valeurs en combinaison avec les autorisations, s'il s'agit de racines et de paramètres de réservation / quota de système de fichiers .

3. Relation avec disk_total_space ()

disk_total_space () renvoie le nombre total d'octets (capacité totale) de la partition, tandis que diskfreespace () renvoie le nombre d'octets disponibles. Le taux d'utilisation peut être calculé en combinant les deux:

 <span><span><span class="hljs-variable">$path</span></span><span> = </span><span><span class="hljs-string">'/'</span></span><span>;
</span><span><span class="hljs-variable">$total</span></span><span> = </span><span><span class="hljs-title function_ invoke__">disk_total_space</span></span><span>(</span><span><span class="hljs-variable">$path</span></span><span>);
</span><span><span class="hljs-variable">$free</span></span><span>  = </span><span><span class="hljs-title function_ invoke__">diskfreespace</span></span><span>(</span><span><span class="hljs-variable">$path</span></span><span>);

</span><span><span class="hljs-keyword">if</span></span><span> (</span><span><span class="hljs-variable">$total</span></span><span> &amp;&amp; </span><span><span class="hljs-variable">$free</span></span><span> !== </span><span><span class="hljs-literal">false</span></span><span>) {
    </span><span><span class="hljs-variable">$used</span></span><span> = </span><span><span class="hljs-variable">$total</span></span><span> - </span><span><span class="hljs-variable">$free</span></span><span>;
    </span><span><span class="hljs-variable">$usedPercent</span></span><span> = </span><span><span class="hljs-variable">$total</span></span><span> &gt; </span><span><span class="hljs-number">0</span></span><span> ? (</span><span><span class="hljs-variable">$used</span></span><span> / </span><span><span class="hljs-variable">$total</span></span><span>) * </span><span><span class="hljs-number">100</span></span><span> : </span><span><span class="hljs-number">0</span></span><span>;
    </span><span><span class="hljs-title function_ invoke__">printf</span></span><span>(</span><span><span class="hljs-string">"Capacité totale: %s, Disponible: %s, Utilisé: %.2f%%\n"</span></span><span>, </span><span><span class="hljs-title function_ invoke__">formatBytes</span></span><span>(</span><span><span class="hljs-variable">$total</span></span><span>), </span><span><span class="hljs-title function_ invoke__">formatBytes</span></span><span>(</span><span><span class="hljs-variable">$free</span></span><span>), </span><span><span class="hljs-variable">$usedPercent</span></span><span>);
}
</span></span>

4. Unités numériques et comment afficher (points d'erreur courants)

Il existe deux unités couramment utilisées pour l'espace disque:

Binaire (couramment utilisé dans les systèmes d'exploitation): 1 kib = 1024 octets, 1 MIB = 1024 kib = 10242 octets, 1 gib = 10243 octets.
Décimal (certains fabricants ou spécifications du disque dur): 1 kb = 1000 octets, 1 Mo = 10002 octets.

PHP renvoie le nombre d'octets. Si vous avez besoin d'un écran "lisible par l'homme", il est généralement converti en outils binaires (1024) des outils du système d'exploitation ( DF -H , etc. Affichez généralement GIB):

 <span><span><span class="hljs-function"><span class="hljs-keyword">function</span></span></span><span> </span><span><span class="hljs-title">formatBytes</span></span><span>(</span><span><span class="hljs-params"><span class="hljs-variable">$bytes</span></span></span><span>, </span><span><span class="hljs-variable">$precision</span></span><span> = </span><span><span class="hljs-number">2</span></span><span>) {
    </span><span><span class="hljs-keyword">if</span></span><span> (!</span><span><span class="hljs-title function_ invoke__">is_numeric</span></span><span>(</span><span><span class="hljs-variable">$bytes</span></span><span>) || </span><span><span class="hljs-variable">$bytes</span></span><span> &lt; </span><span><span class="hljs-number">0</span></span><span>) </span><span><span class="hljs-keyword">return</span></span><span> </span><span><span class="hljs-string">'0 B'</span></span><span>;
    </span><span><span class="hljs-variable">$units</span></span><span> = [</span><span><span class="hljs-string">'B'</span></span><span>,</span><span><span class="hljs-string">'KiB'</span></span><span>,</span><span><span class="hljs-string">'MiB'</span></span><span>,</span><span><span class="hljs-string">'GiB'</span></span><span>,</span><span><span class="hljs-string">'TiB'</span></span><span>,</span><span><span class="hljs-string">'PiB'</span></span><span>];
    </span><span><span class="hljs-variable">$i</span></span><span> = </span><span><span class="hljs-number">0</span></span><span>;
    </span><span><span class="hljs-keyword">while</span></span><span> (</span><span><span class="hljs-variable">$bytes</span></span><span> &gt;= </span><span><span class="hljs-number">1024</span></span><span> &amp;&amp; </span><span><span class="hljs-variable">$i</span></span><span> &lt; </span><span><span class="hljs-title function_ invoke__">count</span></span><span>(</span><span><span class="hljs-variable">$units</span></span><span>)-</span><span><span class="hljs-number">1</span></span><span>) {
        </span><span><span class="hljs-variable">$bytes</span></span><span> /= </span><span><span class="hljs-number">1024</span></span><span>;
        </span><span><span class="hljs-variable">$i</span></span><span>++;
    }
    </span><span><span class="hljs-keyword">return</span></span><span> </span><span><span class="hljs-title function_ invoke__">round</span></span><span>(</span><span><span class="hljs-variable">$bytes</span></span><span>, </span><span><span class="hljs-variable">$precision</span></span><span>) . </span><span><span class="hljs-string">' '</span></span><span> . </span><span><span class="hljs-variable">$units</span></span><span>[</span><span><span class="hljs-variable">$i</span></span><span>];
}
</span></span>

Exemple: 1073741824 octets = 1073741824/1024 ^ 3 = 1 gib (c'est-à-dire 1gib).

5. Pièges communs et pratiques recommandées

Débordement 32 bits : sur PHP 32 bits, un plus grand nombre d'octets peut être hors de la plage int , entraînant des erreurs ou des approximations de points flottants. Essayez d'exécuter dans un environnement 64 bits ou utilisez Float / String pour traiter de grands nombres.
Vérifiez la valeur de retour : renvoyer false lorsque la fonction échoue, appliquez === false pour juger l'erreur, au lieu de if (! $ Gratuit) (car 0 octets est également une fausse valeur).
Autorisations et blocs de rétention : réalisez qu'il est renvoyé avec un espace "Visible / Disponible pour l'espace actuel" - si vous exécutez en tant qu'utilisateur de serveur Web, le résultat peut être inférieur à celui du superutilisateur disponible.
Système de fichiers réseau (NFS / SMB) : Ces supports peuvent retourner instables ou affectés par les options de montage et doivent être testés en conjonction avec une configuration de montage spécifique.
Surveillance rapide : si elle est utilisée pour les alarmes (telles que l'utilisation du disque> 90%), utilisez une combinaison de disque_total_space () et de diskfreespace () et définissez le seuil conservateur pour éviter d'être induit en erreur par des blocs ou des quotas conservés.

6. Exemple complet: Obtenez l'espace disponible et alerte par pourcentage

 <span><span><span class="hljs-meta">&lt;?php</span></span><span>
</span><span><span class="hljs-variable">$path</span></span><span> = </span><span><span class="hljs-string">'/'</span></span><span>; </span><span><span class="hljs-comment">// Le chemin à détecter</span></span><span>
</span><span><span class="hljs-variable">$total</span></span><span> = @</span><span><span class="hljs-title function_ invoke__">disk_total_space</span></span><span>(</span><span><span class="hljs-variable">$path</span></span><span>);
</span><span><span class="hljs-variable">$free</span></span><span>  = @</span><span><span class="hljs-title function_ invoke__">diskfreespace</span></span><span>(</span><span><span class="hljs-variable">$path</span></span><span>);

</span><span><span class="hljs-keyword">if</span></span><span> (</span><span><span class="hljs-variable">$total</span></span><span> === </span><span><span class="hljs-literal">false</span></span><span> || </span><span><span class="hljs-variable">$free</span></span><span> === </span><span><span class="hljs-literal">false</span></span><span>) {
    </span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"Impossible d&#39;obtenir des informations sur disque（Ce peut être une erreur de chemin ou des autorisations insuffisantes）\n"</span></span><span>;
    </span><span><span class="hljs-keyword">exit</span></span><span>(</span><span><span class="hljs-number">1</span></span><span>);
}

</span><span><span class="hljs-variable">$used</span></span><span> = </span><span><span class="hljs-variable">$total</span></span><span> - </span><span><span class="hljs-variable">$free</span></span><span>;
</span><span><span class="hljs-variable">$usedPercent</span></span><span> = </span><span><span class="hljs-variable">$total</span></span><span> &gt; </span><span><span class="hljs-number">0</span></span><span> ? (</span><span><span class="hljs-variable">$used</span></span><span> / </span><span><span class="hljs-variable">$total</span></span><span>) * </span><span><span class="hljs-number">100</span></span><span> : </span><span><span class="hljs-number">0</span></span><span>;

</span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"chemin: <span class="hljs-subst">$path</span></span></span><span>\n";
</span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"Capacité totale: "</span></span><span> . </span><span><span class="hljs-title function_ invoke__">formatBytes</span></span><span>(</span><span><span class="hljs-variable">$total</span></span><span>) . </span><span><span class="hljs-string">"\n"</span></span><span>;
</span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"Disponible: "</span></span><span>     . </span><span><span class="hljs-title function_ invoke__">formatBytes</span></span><span>(</span><span><span class="hljs-variable">$free</span></span><span>)  . </span><span><span class="hljs-string">"\n"</span></span><span>;
</span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"Utilisé: "</span></span><span>     . </span><span><span class="hljs-title function_ invoke__">number_format</span></span><span>(</span><span><span class="hljs-variable">$usedPercent</span></span><span>, </span><span><span class="hljs-number">2</span></span><span>) . </span><span><span class="hljs-string">"%\n"</span></span><span>;

</span><span><span class="hljs-keyword">if</span></span><span> (</span><span><span class="hljs-variable">$usedPercent</span></span><span> &gt;= </span><span><span class="hljs-number">90</span></span><span>) {
    </span><span><span class="hljs-comment">// Exemple de logique d&#39;alarme</span></span><span>
    </span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"avertir：Le disque a été utilisé depuis plus que 90%！\n"</span></span><span>;
}

</span><span><span class="hljs-comment">// formatBytes La fonction est la même que ci-dessus</span></span><span>
</span></span>

7. Résumé (examen des points clés)

DiskFreespace () Renvoie des octets , représentant l'espace disponible pour le processus PHP actuel à ce point de montage , plutôt que la "quantité de ralenti absolu" qui peut être utilisée par tous les utilisateurs du disque.
Les résultats sont affectés par les blocs réservés au système de fichiers, les autorisations, les quotas, les supports de réseau et l'environnement de fonctionnement (conteneurs / machines virtuelles).
Lors de l'affichage, convertissez-le en kib / mib / gib selon une cardinalité 1024, qui est plus proche des méthodes d'affichage communes du système d'exploitation.
Vérifiez toujours === FALSE pour gérer l'erreur et faites attention aux grands nombres débordant dans des environnements 32 bits.

Connexe

diskfreespace () la signification et l'unité de la valeur de retour