ftp_fget()

Qu'est-ce que ftp_fget() ?

ftp_fget() télécharge un fichier depuis un serveur FTP et l'écrit dans un descripteur de fichier local déjà ouvert. C'est la différence clé avec ftp_get() : ftp_get() prend un chemin local et crée le fichier à votre place, tandis que ftp_fget() prend une ressource de fichier déjà ouverte (la valeur retournée par fopen()). Puisque vous contrôlez le descripteur, ftp_fget() est pratique lorsque vous souhaitez écrire dans un flux qui n'est pas un fichier ordinaire — un flux temporaire (php://temp), un tampon en mémoire, ou un descripteur que vous avez positionné avec fseek().

Cette page couvre la signature de la fonction, un téléchargement complet fonctionnel, comment choisir un mode de transfert, comment reprendre un téléchargement interrompu, et la gestion des erreurs nécessaire dans du code réel.

L'extension FTP procédurale fait toujours partie de PHP. Depuis PHP 8.1, la connexion est un objet FTP\Connection plutôt qu'une resource, mais le code que vous écrivez reste inchangé. Pour les transferts chiffrés, utilisez ftp_ssl_connect() à la place de ftp_connect().

Syntaxe de ftp_fget()

ftp_fget(
    FTP\Connection $ftp,
    resource $stream,
    string $remote_filename,
    int $mode = FTP_BINARY,
    int $offset = 0
): bool

La fonction retourne true en cas de succès et false en cas d'échec.

Télécharger un fichier avec ftp_fget()

Un téléchargement complet comporte quatre étapes : se connecter, se connecter, ouvrir un descripteur local, puis récupérer. Fermez toujours le descripteur et la connexion quand vous avez terminé.

<?php

// 1. Connect (returns false on failure)
$ftp = ftp_connect('ftp.example.com');
if ($ftp === false) {
    exit("Could not connect to the FTP server.\n");
}

// 2. Authenticate
if (!ftp_login($ftp, 'username', 'password')) {
    exit("FTP login failed.\n");
}

// Most networks need passive mode so the data channel works behind NAT/firewalls
ftp_pasv($ftp, true);

// 3. Open a local handle for writing
$handle = fopen('downloads/report.pdf', 'w');

// 4. Download into that handle (binary mode for a PDF)
if (ftp_fget($ftp, $handle, 'public/report.pdf', FTP_BINARY)) {
    echo "Download complete.\n";
} else {
    echo "Download failed.\n";
}

fclose($handle);
ftp_close($ftp);

Appeler ftp_pasv() pour activer le mode passif est presque toujours nécessaire lorsque le client se trouve derrière un pare-feu ou un NAT, ce qui est le cas courant ; sans cela, le transfert de données peut se bloquer.

Choisir un mode de transfert

• FTP_BINARY copie le fichier octet par octet. Utilisez-le pour les images, les archives, les PDF, les exécutables — tout ce qui n'est pas du texte brut. C'est la valeur par défaut sûre.
• FTP_ASCII convertit les fins de ligne pour correspondre à la plateforme de destination. Utilisez-le uniquement pour les fichiers texte, et seulement lorsque vous souhaitez réellement cette conversion. L'envoi d'un fichier binaire en mode ASCII le corrompt.

Reprendre un téléchargement interrompu

Le paramètre $offset vous permet de continuer un téléchargement qui a été interrompu. Ouvrez le fichier partiel existant en mode ajout, déterminez combien d'octets vous avez déjà, et indiquez à ftp_fget() de commencer à écrire à partir de là :

<?php

$local = 'downloads/big.iso';

// Open in append mode so previously downloaded bytes are preserved
$handle = fopen($local, 'a');

// How many bytes we already have locally
$alreadyHave = file_exists($local) ? filesize($local) : 0;

if (ftp_fget($ftp, $handle, 'images/big.iso', FTP_BINARY, $alreadyHave)) {
    echo "Resumed and finished the download.\n";
}

fclose($handle);

Pour les très grands fichiers, vous préférerez peut-être la variante non bloquante ftp_nb_fget(), qui rend le contrôle à votre script entre les blocs afin que vous puissiez afficher la progression.

Gestion des erreurs

ftp_fget() retourne uniquement false — elle ne lève pas d'exception — alors vérifiez la valeur de retour de chaque étape, pas seulement du téléchargement. La comparaison avec === évite de traiter incorrectement une valeur fausse mais valide.

<?php

$handle = fopen('downloads/data.csv', 'w');
if ($handle === false) {
    exit("Could not open the local file for writing.\n");
}

if (ftp_fget($ftp, $handle, 'exports/data.csv', FTP_ASCII) === false) {
    // Common causes: wrong remote path, no read permission, or a dropped data channel
    echo "Failed to retrieve the file.\n";
} else {
    echo "File retrieved successfully.\n";
}

fclose($handle);

Pièges courants

• Passer un chemin au lieu d'un descripteur. Le deuxième argument doit être une ressource issue de fopen(). Si vous avez un chemin, utilisez plutôt ftp_get().
• Oublier le mode passif. Derrière un pare-feu, si vous omettez ftp_pasv(), le transfert peut se bloquer silencieusement.
• Mauvais mode de transfert. Le mode ASCII altère les fichiers binaires ; le mode binaire laisse des fins de ligne parasites dans les fichiers texte uniquement sur de rares plateformes, donc le binaire est la valeur par défaut la plus sûre.
• Ne pas fermer les ressources. Appelez fclose() et ftp_close() pour vider les tampons et libérer la connexion.

Fonctions associées

• ftp_get() — télécharger vers un chemin local (sans descripteur nécessaire).
• ftp_fput() — la contrepartie pour l'envoi, depuis un descripteur ouvert.
• ftp_nb_fget() — téléchargement non bloquant dans un descripteur.
• ftp_connect() et ftp_login() — ouvrir et authentifier la session.

Entraînement