ftp_nb_get()

Comprendre la fonction PHP ftp_nb_get()

La fonction ftp_nb_get() télécharge un fichier depuis un serveur FTP en mode non bloquant. Contrairement à son équivalent bloquant ftp_get(), qui suspend l'exécution de votre script jusqu'à ce que le fichier entier soit transféré, ftp_nb_get() rend immédiatement le contrôle à votre programme afin que vous puissiez effectuer d'autres tâches pendant que le téléchargement s'exécute en arrière-plan.

Cette page explique quand utiliser la variante non bloquante, détaille chaque paramètre et valeur de retour, et présente un modèle de fonctionnement complet avec ftp_nb_continue().

Quand utiliser le mode non bloquant

Le « nb » dans le nom signifie non bloquant (non-blocking). Utilisez ftp_nb_get() à la place de ftp_get() lorsque :

• Vous souhaitez afficher la progression ou maintenir une interface réactive pendant le téléchargement d'un fichier volumineux.
• Vous devez intercaler d'autres tâches (journalisation, envoi de signaux d'activité, traitement des données déjà téléchargées) pendant le transfert.
• Vous souhaitez imposer votre propre logique de délai d'attente ou d'annulation dans la boucle d'interrogation.

Pour un simple « télécharger ce fichier et attendre », ftp_get() est plus simple et constitue le meilleur choix. L'inconvénient est que le mode non bloquant vous oblige à piloter le transfert vous-même dans une boucle avec ftp_nb_continue().

Qu'est-ce que ftp_nb_get() ?

La fonction ftp_nb_get() initie un téléchargement de fichier asynchrone. Elle nécessite quatre paramètres :

1. ftp_stream : L'identifiant de connexion renvoyé par ftp_connect().
2. local_file : Le chemin du fichier local où le fichier téléchargé sera enregistré.
3. remote_file : Le chemin vers le fichier distant sur le serveur FTP.
4. mode : Le mode de transfert, soit FTP_ASCII soit FTP_BINARY.

Elle accepte également un cinquième paramètre optionnel, resumepos, qui spécifie la position dans le fichier distant à partir de laquelle démarrer le téléchargement (par défaut 0).

La fonction retourne l'une des trois constantes suivantes :

Comme la fonction peut retourner avant que le téléchargement soit terminé, vous la combinez presque toujours avec ftp_nb_continue() dans une boucle qui s'exécute tant que le résultat est FTP_MOREDATA.

Syntaxe de ftp_nb_get()

La syntaxe de la fonction ftp_nb_get() est la suivante :

Syntaxe de ftp_nb_get()

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

La fonction ftp_nb_get() prend quatre paramètres obligatoires (ftp_stream, local_file, remote_file et mode) et un paramètre optionnel (resumepos). Le paramètre ftp_stream est l'identifiant de connexion renvoyé par ftp_connect(). Le paramètre local_file est le chemin vers le fichier local où le fichier téléchargé sera enregistré. Le paramètre remote_file est le chemin vers le fichier distant sur le serveur FTP. Le paramètre mode spécifie le mode de transfert, soit FTP_ASCII soit FTP_BINARY. Le paramètre resumepos spécifie la position dans le fichier distant à partir de laquelle démarrer le téléchargement. Par défaut, resumepos est défini à 0, ce qui signifie que le téléchargement démarrera depuis le début du fichier.

Utilisation de ftp_nb_get()

Pour utiliser la fonction ftp_nb_get(), vous devez d'abord établir une connexion au serveur FTP à l'aide de ftp_connect(). Voici un exemple :

Utilisation de ftp_nb_get()

<?php

// Set up an FTP connection
$conn = ftp_connect('ftp.example.com');

// Login with your FTP credentials
ftp_login($conn, 'username', 'password');

// Initiate an asynchronous FTP operation
$result = ftp_nb_get($conn, 'local_file.txt', 'remote_file.txt', FTP_BINARY);

if ($result === FTP_FAILED) {
    echo "Failed to download file from remote server.\n";
} else {
    // Continue the asynchronous FTP operation
    while ($result === FTP_MOREDATA) {
        // Do something else while waiting for the FTP operation to complete
        $result = ftp_nb_continue($conn);
    }
}

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

Dans cet exemple, nous établissons une connexion au serveur FTP à l'aide de ftp_connect(). Ensuite, nous nous connectons avec nos identifiants FTP via ftp_login(). Nous initions une opération FTP asynchrone avec ftp_nb_get(). Nous poursuivons l'opération à l'aide de ftp_nb_continue() dans une boucle qui vérifie FTP_MOREDATA, et enfin nous fermons la connexion FTP.

Reprendre un téléchargement interrompu

Le cinquième paramètre optionnel, resumepos, vous permet de reprendre un fichier partiellement téléchargé plutôt que de recommencer depuis le début. Passez le décalage en octets à partir duquel reprendre — généralement la taille du fichier déjà présent sur le disque :

Reprise d'un téléchargement avec resumepos

<?php

$local = 'big-archive.zip';

// If a partial file already exists, resume from where it left off.
$resumePos = file_exists($local) ? filesize($local) : 0;

$result = ftp_nb_get($conn, $local, 'big-archive.zip', FTP_BINARY, $resumePos);

while ($result === FTP_MOREDATA) {
    $result = ftp_nb_continue($conn);
}

Ceci est particulièrement utile pour les fichiers volumineux sur des connexions peu fiables, où vous ne souhaitez pas re-télécharger des données que vous avez déjà.

Gestion des erreurs dans ftp_nb_get()

Vérifiez toujours la valeur de retour. ftp_nb_get() retourne FTP_FAILED lorsqu'elle ne peut pas démarrer (ou continuer) le transfert, et ftp_nb_continue() peut également retourner FTP_FAILED en cours de transfert. Gérez les deux cas :

Gestion des erreurs dans ftp_nb_get()

<?php

$conn = ftp_connect('ftp.example.com');

if ($conn === false || !ftp_login($conn, 'username', 'password')) {
    exit("Could not connect or log in to the FTP server.\n");
}

$result = ftp_nb_get($conn, 'local_file.txt', 'remote_file.txt', FTP_BINARY);

// Drive the transfer to completion, watching for failure at every step.
while ($result === FTP_MOREDATA) {
    $result = ftp_nb_continue($conn);
}

if ($result === FTP_FINISHED) {
    echo "File downloaded successfully.\n";
} else {
    echo "Failed to download file from remote server.\n";
}

ftp_close($conn);

En vérifiant séparément la connexion, l'authentification et l'état final du transfert, vous pouvez identifier précisément où une opération FTP a échoué.

Fonctions associées

• ftp_get() — la version bloquante qui télécharge un fichier et attend la fin du transfert.
• ftp_nb_continue() — poursuit un transfert non bloquant démarré par ftp_nb_get().
• ftp_nb_fget() — similaire à ftp_nb_get(), mais écrit dans un pointeur de fichier ouvert plutôt que dans un chemin.
• ftp_connect() et ftp_login() — établissent et authentifient la session FTP.
• ftp_close() — ferme la connexion lorsque vous avez terminé.

Conclusion

La fonction ftp_nb_get() télécharge des fichiers depuis un serveur FTP en mode non bloquant, permettant à votre script de rester réactif pendant l'exécution d'un transfert. Combinez-la avec ftp_nb_continue() dans une boucle, vérifiez la valeur de retour par rapport à FTP_FINISHED et FTP_FAILED, et utilisez resumepos pour récupérer les téléchargements interrompus.

Pratique