ftp_nb_fput()

Comprendre la fonction PHP ftp_nb_fput()

La fonction ftp_nb_fput() est une fonction PHP intégrée qui envoie un fichier vers un serveur FTP en utilisant le mode non-bloquant. « Non-bloquant » signifie que la fonction rend le contrôle à votre script avant la fin du transfert, ce qui vous permet d'exécuter d'autres opérations (mettre à jour une barre de progression, traiter une autre tâche) pendant que l'envoi est encore en cours. Cet article explique les paramètres, les valeurs de retour et un modèle de fonctionnement complet pour l'utiliser dans vos projets PHP.

La contrepartie bloquante est ftp_fput(), qui attend simplement que le fichier entier soit envoyé. Utilisez ftp_nb_fput() uniquement lorsque vous avez besoin d'effectuer des opérations pendant le transfert.

Qu'est-ce que ftp_nb_fput() ?

La fonction ftp_nb_fput() envoie un fichier vers un serveur FTP en mode non-bloquant. Elle accepte quatre paramètres obligatoires et un paramètre optionnel :

1. ftp_stream : L'identifiant de connexion retourné par ftp_connect().
2. remote_file : Le chemin vers le fichier distant sur le serveur FTP.
3. handle : Un pointeur de fichier ouvert vers le fichier local.
4. mode : Le mode de transfert, soit FTP_ASCII, soit FTP_BINARY.
5. startpos (optionnel) : La position dans le fichier distant à partir de laquelle commencer l'envoi. Par défaut, vaut 0.

La fonction retourne l'une des constantes suivantes : FTP_SUCCESS (envoi terminé), FTP_MOREDATA (des données supplémentaires doivent être lues) ou FTP_FAILED (une erreur s'est produite).

Syntaxe de ftp_nb_fput()

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

int ftp_nb_fput ( resource $ftp_stream , string $remote_file , resource $handle , int $mode [, int $startpos = 0 ] )

La fonction prend quatre paramètres obligatoires (ftp_stream, remote_file, handle et mode) et un paramètre optionnel (startpos). Le paramètre ftp_stream est l'identifiant de connexion retourné par ftp_connect(). Le paramètre remote_file est le chemin vers le fichier distant sur le serveur FTP. Le paramètre handle est un pointeur de fichier ouvert dans le système de fichiers local. Le paramètre mode spécifie le mode de transfert, soit FTP_ASCII, soit FTP_BINARY. Le paramètre startpos spécifie la position dans le fichier distant à partir de laquelle commencer l'envoi. Par défaut, startpos est défini à 0, ce qui signifie que l'envoi commencera depuis le début du fichier.

Utilisation de ftp_nb_fput()

Pour utiliser la fonction ftp_nb_fput(), vous devez d'abord établir une connexion au serveur FTP avec la fonction ftp_connect() et vous authentifier avec ftp_login(). Voici un exemple complet :

<?php

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

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

// Enable passive mode to prevent transfer issues
ftp_pasv($conn, true);

// Open a file for reading
$handle = fopen('local_file.txt', 'r');

// Initiate an asynchronous FTP operation
$res = ftp_nb_fput($conn, 'remote_file.txt', $handle, FTP_BINARY);

// Continue the asynchronous FTP operation
while ($res == FTP_MOREDATA) {
    $res = ftp_nb_continue($conn);
}

// Check for errors
if ($res != FTP_FAILED && $res != FTP_SUCCESS) {
    echo "FTP upload failed.\n";
}

// Close the file
fclose($handle);

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

Dans cet exemple, nous établissons une connexion au serveur FTP, nous nous connectons avec nos identifiants et activons le mode passif avec ftp_pasv() pour éviter les problèmes de transfert courants derrière des pare-feux. Nous ouvrons le fichier local en lecture, puis appelons ftp_nb_fput() pour démarrer l'envoi. Le détail clé est la boucle while : tant que ftp_nb_fput() (ou les appels suivants) retourne FTP_MOREDATA, nous maintenons le transfert en mouvement avec ftp_nb_continue(). Dans une application réelle, chaque itération de cette boucle est l'endroit où vous effectueriez d'autres opérations, puisque le transfert est non-bloquant.

Gestion des erreurs dans ftp_nb_fput()

Il est important de gérer correctement les erreurs lors de l'utilisation de la fonction ftp_nb_fput(). La fonction retourne des constantes spécifiques plutôt qu'un boolean, vous devez donc vérifier FTP_FAILED pour détecter les erreurs. Voici un exemple de gestion des erreurs :

<?php

// Assume $conn is already established and logged in
$handle = fopen('local_file.txt', 'r');
$res = ftp_nb_fput($conn, 'remote_file.txt', $handle, FTP_BINARY);

if ($res == FTP_FAILED) {
    echo "Failed to initiate upload.\n";
}

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

if ($res == FTP_FAILED) {
    echo "Failed to complete upload.\n";
}

fclose($handle);
ftp_close($conn);

En gérant les erreurs de manière appropriée et en vérifiant les constantes de retour de ftp_nb_fput() et de ftp_nb_continue(), vous pouvez garantir le succès de vos opérations FTP.

ftp_nb_fput() vs. fonctions connexes

PHP propose plusieurs fonctions d'envoi FTP. Le choix de la bonne fonction dépend de si vous disposez d'un pointeur de fichier ouvert ou simplement d'un chemin, et si vous avez besoin d'un comportement non-bloquant :

• ftp_fput() — envoie depuis un pointeur de fichier ouvert, en bloquant jusqu'à la fin.
• ftp_put() — envoie depuis un chemin de fichier local, en bloquant jusqu'à la fin.
• ftp_nb_put() — envoi non-bloquant depuis un chemin de fichier local (même modèle de boucle que cette fonction).
• ftp_nb_fput() — envoi non-bloquant depuis un pointeur de fichier ouvert (cette fonction).

Toutes les variantes non-bloquantes partagent le même modèle de boucle FTP_MOREDATA / ftp_nb_continue().

Conclusion

La fonction ftp_nb_fput() envoie un fichier vers un serveur FTP en mode non-bloquant, permettant à votre script de continuer à exécuter d'autres opérations pendant que le transfert est en cours. Le modèle essentiel est : démarrer l'envoi, puis boucler avec ftp_nb_continue() tant que la valeur de retour est FTP_MOREDATA, et vérifier FTP_FAILED à chaque étape. Utilisée correctement, elle améliore la réactivité du code de transfert de fichiers dans vos projets PHP.

Pratique