ftp_get()

Qu'est-ce que ftp_get() ?

ftp_get() est une fonction native PHP qui télécharge un fichier depuis un serveur FTP et l'écrit dans un fichier local sur votre machine. C'est l'équivalent en lecture de ftp_put(), qui effectue un envoi. Utilisez-la chaque fois que vous devez récupérer un fichier (une sauvegarde, un journal, un rapport) depuis un serveur distant via FTP.

Cette page présente le rôle de ftp_get(), ses paramètres et sa valeur de retour, un flux de travail complet (connexion → authentification → téléchargement → fermeture), la gestion des erreurs, et les pièges courants (mode de transfert, mode passif, et reprise des téléchargements partiels).

Paramètres

ftp_get() accepte cinq paramètres — trois obligatoires et deux facultatifs :

Valeur de retour

La fonction retourne un boolean : true en cas de succès, false en cas d'échec. Vérifiez-la systématiquement — un téléchargement échoué ne lève pas d'exception par défaut.

FTP_BINARY vs FTP_ASCII

FTP_BINARY transfère le fichier octet par octet et convient à presque tout : images, PDF, archives, exécutables, et même la plupart des fichiers texte. FTP_ASCII effectue une conversion automatique des fins de ligne entre les conventions du serveur et du client ; utilisez-le uniquement pour les fichiers en texte brut lorsque vous souhaitez réellement cette conversion. L'utilisation de FTP_ASCII sur un fichier binaire le corrompra, donc en cas de doute, choisissez FTP_BINARY.

Syntaxe de ftp_get()

bool ftp_get ( resource $ftp_stream , string $local_file , string $remote_file [, int $mode = FTP_BINARY [, int $resumepos = 0 ]] )

Note : en PHP 8.1+, le type resource pour les connexions FTP a été remplacé par un objet Ftp\Connection, et le paramètre mode est devenu facultatif (par défaut FTP_BINARY). La signature resource héritée ci-dessus est conservée pour la compatibilité ascendante — votre code n'a pas besoin d'être modifié.

Utilisation de ftp_get()

Pour utiliser ftp_get(), vous devez d'abord établir une connexion avec ftp_connect() et vous authentifier avec ftp_login(). Voici le flux complet :

Téléchargement d'un fichier avec ftp_get()

<?php
// 1. Set up an FTP connection
$conn = ftp_connect('ftp.example.com');
if (!$conn) {
    die("Could not connect to FTP server.\n");
}

// 2. Log in with your FTP credentials
if (!ftp_login($conn, 'username', 'password')) {
    ftp_close($conn);
    die("Login failed.\n");
}

// 3. Switch to passive mode (required behind most firewalls/NAT)
ftp_pasv($conn, true);

// 4. Download the remote file into a local path
if (ftp_get($conn, '/local/directory/local_file.txt', 'remote_file.txt', FTP_BINARY)) {
    echo "File retrieved successfully.\n";
} else {
    echo "Failed to retrieve the file.\n";
}

// 5. Close the FTP connection
ftp_close($conn);

Les étapes sont toujours les mêmes : connexion, authentification, activation optionnelle du mode passif, téléchargement, puis fermeture. Le mode passif (ftp_pasv()) est activé ici car la plupart des clients se trouvent derrière un pare-feu ou un NAT, et les transferts en mode actif risqueraient sinon de se bloquer ou d'échouer. Notez que vous devez appeler ftp_pasv() après vous être authentifié.

Gestion des erreurs dans ftp_get()

ftp_get() retourne false en cas d'échec plutôt que de lever une exception ; vérifiez donc explicitement la valeur de retour. Les causes courantes sont un fichier distant absent, des permissions insuffisantes, ou un chemin local non accessible en écriture. PHP émet également un avertissement que vous pouvez capturer pour la journalisation :

Capturer la raison d'un échec de téléchargement

<?php
// $conn is an open, logged-in FTP connection
$ok = @ftp_get($conn, '/local/directory/local_file.txt', 'remote_file.txt', FTP_BINARY);

if ($ok === false) {
    $error = error_get_last();
    echo "Failed to retrieve the file: " . ($error['message'] ?? 'unknown error') . "\n";
} else {
    echo "File retrieved successfully.\n";
}

Le @ supprime l'avertissement PHP brut pour vous permettre de formater votre propre message, tandis que error_get_last() vous fournit toujours le détail sous-jacent pour un journal.

Reprendre un téléchargement interrompu

Le paramètre facultatif resumepos vous permet de poursuivre un téléchargement qui a été interrompu, plutôt que de recommencer depuis le début. Passez la taille actuelle du fichier local partiellement téléchargé comme décalage en octets :

Reprendre avec resumepos

<?php
// $conn is an open, logged-in FTP connection
$local = '/local/directory/big_archive.zip';

// Continue from however many bytes we already have locally
$offset = file_exists($local) ? filesize($local) : 0;

if (ftp_get($conn, $local, 'big_archive.zip', FTP_BINARY, $offset)) {
    echo "Download complete.\n";
} else {
    echo "Resume failed.\n";
}

La reprise ne fonctionne de manière fiable qu'avec FTP_BINARY et sur des serveurs qui supportent la commande REST. Pour les transferts volumineux, vous pouvez aussi utiliser la variante non bloquante ftp_nb_get(), qui télécharge en arrière-plan afin que votre script puisse effectuer d'autres opérations.

Fonctions associées

• ftp_put() — envoyer un fichier local vers le serveur (l'inverse de ftp_get()).
• ftp_fget() — télécharger dans un gestionnaire de fichier déjà ouvert plutôt que vers un chemin.
• ftp_size() — obtenir la taille d'un fichier distant avant de le télécharger.
• ftp_connect() et ftp_login() — ouvrir et authentifier la connexion.
• ftp_close() — fermer la connexion une fois que vous avez terminé.

Résumé

ftp_get() télécharge un fichier distant via FTP et l'enregistre localement, retournant true en cas de succès et false en cas d'échec. Connectez-vous et authentifiez-vous d'abord, préférez FTP_BINARY sauf si vous avez spécifiquement besoin de la conversion des fins de ligne ASCII, activez le mode passif lorsque vous êtes derrière un pare-feu, et vérifiez toujours la valeur de retour pour que les échecs ne passent pas silencieusement.

Exercice