ftp_nb_continue()

Qu'est-ce que ftp_nb_continue() ?

ftp_nb_continue() est une fonction PHP intégrée qui reprend — ou continue — un transfert de fichier FTP non bloquant démarré précédemment. Le nb dans le nom signifie non-bloquant : au lieu de figer votre script jusqu'à ce qu'un fichier entier soit envoyé ou téléchargé, les fonctions FTP non bloquantes rendent le contrôle après chaque bloc, afin que votre script puisse effectuer d'autres tâches entre-temps.

Cette page explique ce que retourne la fonction, comment fonctionne la boucle de transfert non bloquant, comment gérer les erreurs et les pièges courants.

Comment fonctionnent les transferts non bloquants

Un transfert normal tel que ftp_get() est bloquant : PHP attend que le fichier entier soit reçu avant que la ligne suivante s'exécute. La famille non bloquante — ftp_nb_get(), ftp_nb_put(), ftp_nb_fget() et ftp_nb_fput() — démarre le transfert et retourne immédiatement. Vous appelez ensuite ftp_nb_continue() de manière répétée pour faire avancer le transfert un bloc à la fois, jusqu'à ce qu'il signale qu'il est terminé.

La fonction retourne l'une de ces trois constantes :

Remarque : la fonction de démarrage (ftp_nb_get() etc.) retourne le même ensemble de constantes, donc votre logique de boucle doit tenir compte de la possibilité que le transfert se termine dès le premier appel.

Syntaxe de ftp_nb_continue()

ftp_nb_continue(resource $ftp): int

Elle prend un seul paramètre, $ftp : l'identifiant de connexion retourné par ftp_connect() ou ftp_ssl_connect().

PHP 8.1+ : la connexion est désormais un objet FTP\Connection au lieu d'une resource, mais votre code n'a pas besoin de changer — vous passez simplement la valeur retournée par ftp_connect().

Utilisation de ftp_nb_continue()

Vous commencez d'abord un transfert non bloquant, puis vous le menez à bien avec une boucle :

<?php

// Open the connection and log in
$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'username', 'password');
ftp_pasv($ftp, true); // passive mode is usually required behind firewalls

// Start a non-blocking download: local_file <- remote_file
$state = ftp_nb_get($ftp, 'local_file.txt', 'remote_file.txt', FTP_BINARY);

// Drive the transfer forward until it finishes or fails
while ($state === FTP_MOREDATA) {
    // You can do other work here while the file streams in
    $state = ftp_nb_continue($ftp);
}

if ($state === FTP_FINISHED) {
    echo "Download complete.\n";
} else {
    echo "Download failed.\n";
}

ftp_close($ftp);

Notez l'ordre des arguments de ftp_nb_get() : il est (connection, local_file, remote_file, mode) — la destination locale vient avant la source distante.

Gestion des erreurs

Vérifiez toujours la valeur de retour à chaque itération. Si ftp_nb_continue() retourne FTP_FAILED, le transfert a échoué et vous devez vous arrêter et le signaler plutôt que de boucler indéfiniment :

<?php

$state = ftp_nb_get($ftp, 'local_file.txt', 'remote_file.txt', FTP_BINARY);

while ($state === FTP_MOREDATA) {
    $state = ftp_nb_continue($ftp);
}

switch ($state) {
    case FTP_FINISHED:
        echo "Transfer succeeded.\n";
        break;
    case FTP_FAILED:
        echo "Transfer failed.\n";
        break;
}

Comme la condition de boucle est === FTP_MOREDATA, elle se termine automatiquement sur FTP_FINISHED et FTP_FAILED — le switch qui suit indique alors lequel s'est produit.

Pièges courants

• Oublier de vérifier la valeur de retour de la fonction de démarrage. Un petit fichier peut se terminer lors de l'appel à ftp_nb_get() lui-même, retournant FTP_FINISHED avant même que la boucle s'exécute. Assigner cette valeur de retour à $state (comme ci-dessus) gère cela correctement.
• Appeler ftp_nb_continue() sans transfert actif. Elle ne fonctionne que lorsqu'une opération non bloquante est en attente ; sinon elle retourne FTP_FAILED.
• Une boucle serrée et vide. Tout l'intérêt du FTP non bloquant est d'effectuer un travail utile entre les appels. Une boucle while vide ne fait qu'attendre inutilement et ne vous donne aucun avantage sur le ftp_get() bloquant.
• Le mode passif. Derrière un pare-feu ou un NAT, vous avez généralement besoin de définir ftp_pasv() à true avant de démarrer le transfert.

Conclusion

ftp_nb_continue() reprend un transfert FTP non bloquant démarré avec ftp_nb_get(), ftp_nb_put(), ftp_nb_fget() ou ftp_nb_fput(). Appelez-la dans une boucle tant qu'elle retourne FTP_MOREDATA, arrêtez-vous sur FTP_FINISHED, et gérez FTP_FAILED — ainsi votre script reste réactif pendant que les fichiers sont transférés en arrière-plan.

Pratique