filesize()

Qu'est-ce que la fonction filesize() ?

filesize() est une fonction PHP intégrée qui retourne la taille d'un fichier, mesurée en octets, sous forme d'entier. C'est la méthode standard pour connaître l'espace disque occupé par un fichier avant de le télécharger, l'afficher, valider un envoi, ou décider de le charger en mémoire.

Cette page couvre la syntaxe, la signification de la valeur de retour, le problème important lié aux résultats mis en cache, comment convertir des octets bruts en chaîne lisible par un humain, et comment gérer en toute sécurité les fichiers manquants ou illisibles.

Syntaxe

filesize(string $filename): int|false

• $filename — Chemin vers le fichier. Il peut s'agir d'un chemin relatif, d'un chemin absolu, ou d'un wrapper URL (par ex. http://, ftp://) lorsque le protocole prend en charge le signalement d'une taille.
• Valeur de retour — La taille du fichier en octets sous forme d'entier, ou false en cas d'échec (par exemple, le fichier n'existe pas ou vous n'avez pas la permission d'y accéder).

La taille étant exprimée en octets, un fichier signalé comme 2048 fait 2 Ko, et 1048576 correspond exactement à 1 Mo.

Un exemple de base

L'exemple ci-dessous crée un petit fichier temporaire, y écrit une chaîne connue et affiche sa taille. Écrire le fichier en premier rend l'exemple entièrement autonome et exécutable :

<?php

$filename = 'example.txt';
file_put_contents($filename, 'Hello, world!'); // 13 bytes

$bytes = filesize($filename);
echo "The file '$filename' is $bytes bytes.";
// The file 'example.txt' is 13 bytes.

La chaîne Hello, world! contient 13 caractères ASCII, donc le fichier fait exactement 13 octets. Pour les fichiers texte en encodage à un octet par caractère, le nombre d'octets est égal au nombre de caractères ; les caractères multi-octets (UTF-8) comptent pour plus d'un octet.

filesize() opère sur le fichier tel qu'il est sur le disque. Elle ne pas compter les octets en mémoire, et pour les liens symboliques, elle retourne la taille du fichier cible.

Gérer un fichier manquant ou illisible

Si le fichier n'existe pas, filesize() retourne false et émet un avertissement. Vérifiez toujours que le fichier existe d'abord pour pouvoir échouer gracieusement :

<?php

$filename = 'does-not-exist.txt';

if (file_exists($filename)) {
    echo filesize($filename) . " bytes";
} else {
    echo "File not found.";
}
// File not found.

Parce que false est loosement égal à 0, n'écrivez jamais if (filesize($f) == 0) pour tester un fichier vide sans avoir d'abord confirmé son existence — un fichier manquant et un fichier vide sembleraient identiques. Voir file_exists() pour la vérification préalable sécurisée.

Le problème du cache (clearstatcache)

PHP met en cache le résultat des fonctions système de fichiers telles que filesize(), filemtime(), et stat() pour des raisons de performance. Si un fichier change pendant l'exécution du même script, filesize() peut retourner l'ancienne taille. Appelez clearstatcache() pour forcer une nouvelle lecture :

<?php

$filename = 'log.txt';
file_put_contents($filename, 'first');
echo filesize($filename) . "\n"; // 5

file_put_contents($filename, 'first-second');
clearstatcache(); // discard the cached size
echo filesize($filename) . "\n"; // 12

Sans l'appel à clearstatcache(), le second echo pourrait toujours afficher 5. C'est la source la plus fréquente de résultats « erronés » de filesize().

Convertir des octets en taille lisible

Les nombres d'octets bruts sont difficiles à lire. Un petit utilitaire les convertit en Ko, Mo, Go, etc. :

<?php

function humanFilesize(int $bytes, int $decimals = 2): string
{
    $units = ['B', 'KB', 'MB', 'GB', 'TB'];
    $factor = (int) floor((strlen((string) $bytes) - 1) / 3);
    $value = $bytes / (1024 ** $factor);

    return number_format($value, $decimals) . ' ' . $units[$factor];
}

echo humanFilesize(13);        // 13.00 B
echo "\n";
echo humanFilesize(2048);      // 2.00 KB
echo "\n";
echo humanFilesize(1048576);   // 1.00 MB

Ici number_format() gère les décimales et 1024 ** $factor divise par la bonne puissance de 1024. Remplacez par round() si vous préférez un résultat numérique sans séparateur de milliers.

Quand utiliser filesize() ?

• Valider les envois — refuser les fichiers dépassant une limite avant de les enregistrer (à associer avec is_uploaded_file()).
• Définir les en-têtes de téléchargement — envoyer un en-tête Content-Length correct pour que les navigateurs puissent afficher une barre de progression.
• Décider comment lire un fichier — pour un fichier volumineux, le lire en flux avec fopen()/fread() plutôt que de tout charger avec file_get_contents().
• Surveillance — vérifier si un fichier journal grossit comme prévu.

Fonctions associées

• file_exists() — vérifier qu'un fichier existe avant de le mesurer.
• filemtime() — obtenir la date de dernière modification d'un fichier.
• filetype() — déterminer si un chemin est un fichier, un répertoire ou un lien.
• file_get_contents() — lire l'intégralité d'un fichier dans une chaîne.

Résumé

filesize() retourne la taille d'un fichier en octets, ou false en cas d'échec. Vérifiez toujours d'abord que le fichier existe, pensez à appeler clearstatcache() lorsqu'un fichier change en cours de script, et convertissez les octets en unité conviviale à l'aide d'un utilitaire lorsque vous affichez le résultat aux utilisateurs.

Pratique