ftp_size()

La fonction PHP ftp_size()

ftp_size() est une fonction PHP intégrée qui interroge un serveur FTP pour obtenir la taille, en octets, d'un fichier distant. Elle est utile lorsque vous avez besoin de connaître le poids d'un fichier sans le télécharger — par exemple, pour afficher une barre de progression, déterminer si un fichier a changé depuis la dernière synchronisation, ignorer les fichiers vides ou vérifier qu'un envoi s'est terminé avec la taille attendue.

Cette page couvre la signature, un exemple complet et fonctionnel, le piège classique qui trébuche presque tout le monde (le mode passif), ainsi que la manière de gérer les valeurs de retour particulières.

Syntaxe

ftp_size(FTP\Connection $ftp, string $filename): int

Valeur de retour : la taille du fichier en octets sous forme d'entier en cas de succès, ou -1 en cas d'erreur.

Important : ftp_size() renvoie l'entier -1 en cas d'échec — et non false. C'est différent de la plupart des autres fonctions FTP, aussi comparez toujours avec -1, pas avec false.

Avant PHP 8.1, l'argument $ftp était une resource ; à partir de PHP 8.1, c'est un objet FTP\Connection. Votre code ne change pas — seul le type sous-jacent évolue.

Utilisation de base

Pour appeler ftp_size(), ouvrez d'abord une connexion avec ftp_connect() et authentifiez-vous avec ftp_login() :

<?php

// Open a connection to the FTP server
$conn = ftp_connect('ftp.example.com');

// Log in with your credentials
ftp_login($conn, 'username', 'password');

// Turn on passive mode (see the note below — this is almost always required)
ftp_pasv($conn, true);

// Ask the server how big the file is
$size = ftp_size($conn, '/public_html/index.php');

if ($size !== -1) {
    echo "The file is {$size} bytes.";
} else {
    echo "Could not determine the file size.";
}

// Always close the connection when you are done
ftp_close($conn);

Mode passif : le piège le plus courant

Si ftp_size() continue de renvoyer -1 alors que le fichier existe clairement, la cause est généralement le mode actif vs passif, et non une faute de frappe dans le chemin. Derrière un pare-feu ou un NAT (ce qui décrit la plupart des serveurs aujourd'hui), le serveur FTP ne peut pas ouvrir un canal de données vers votre client, ce qui bloque la commande SIZE sous-jacente.

Appelez ftp_pasv() après la connexion pour basculer en mode passif, où c'est votre client qui initie chaque connexion :

<?php
ftp_login($conn, 'username', 'password');
ftp_pasv($conn, true); // do this before ftp_size(), ftp_get(), ftp_nlist(), etc.

Le mode de transfert influe sur le résultat

La taille rapportée par un serveur FTP peut dépendre du mode de transfert actuel. En mode ASCII, certains serveurs traduisent les fins de ligne, de sorte que la taille rapportée peut ne pas correspondre au nombre d'octets obtenu en mode binaire. Pour des tailles octet par octet précises, assurez-vous d'être en mode binaire (FTP_BINARY), qui est le mode par défaut pour les requêtes de taille sur la plupart des serveurs et le mode que vous souhaiterez presque toujours pour les fichiers non textuels.

Gestion robuste des erreurs

Puisque ftp_size() signale un échec avec -1, un wrapper fiable vérifie cette valeur spécifique et avertit lorsque la taille est inconnue :

<?php

function remoteFileSize($conn, string $path): ?int
{
    $size = ftp_size($conn, $path);

    if ($size === -1) {
        // The file is missing, the path is wrong, or the SIZE command failed.
        return null;
    }

    return $size;
}

$size = remoteFileSize($conn, '/public_html/index.php');

echo $size === null
    ? "File not found or size unavailable.\n"
    : "Size: {$size} bytes\n";

Utiliser null pour le cas d'échec évite que -1 ne se propage dans les calculs ultérieurs (où il corromprait silencieusement des totaux).

Lister les tailles de plusieurs fichiers

ftp_size() fonctionne sur un seul chemin à la fois. Pour afficher les tailles de tout un répertoire, combinez-la avec ftp_nlist(), qui renvoie un array de noms de fichiers :

<?php

$files = ftp_nlist($conn, '/public_html');

if ($files !== false) {
    foreach ($files as $file) {
        $size = ftp_size($conn, $file);
        $label = $size === -1 ? 'directory or unreadable' : "{$size} bytes";
        echo "{$file}: {$label}\n";
    }
}

Notez que ftp_size() renvoie -1 pour les répertoires, ce qui est pratique pour distinguer les fichiers des dossiers dans un listing.

Fonctions associées

• ftp_connect() — ouvre la connexion à passer à ftp_size().
• ftp_login() — s'authentifie avant toute requête de taille.
• ftp_pasv() — active le mode passif pour que ftp_size() fonctionne correctement.
• ftp_nlist() — liste un répertoire pour récupérer la taille de plusieurs fichiers en boucle.
• ftp_get() — télécharge un fichier une fois sa taille connue.
• ftp_close() — ferme la connexion une fois terminé.
• Vue d'ensemble FTP PHP — toutes les fonctions FTP en un seul endroit.

Conclusion

ftp_size() est le moyen le plus rapide de connaître la taille en octets d'un fichier distant sans le transférer. Retenez les deux règles qui la rendent fiable : activez le mode passif avec ftp_pasv() après la connexion, et testez le résultat contre -1 (pas false) pour détecter les échecs et les répertoires.

Pratique