ftp_nb_put()

Comprendre la fonction PHP ftp_nb_put()

La fonction ftp_nb_put() est une fonction PHP intégrée qui envoie un fichier vers un serveur FTP en mode non bloquant. « Non bloquant » signifie que l'appel retourne immédiatement après le démarrage du transfert sans attendre qu'il se termine, ce qui permet à votre script de continuer à effectuer d'autres tâches pendant que les octets transitent sur le réseau. Ce guide couvre ses paramètres, sa syntaxe, son utilisation et la gestion des erreurs pour vous permettre de l'intégrer efficacement dans vos projets PHP.

La fonction sœur de cette fonction est ftp_put(), qui envoie en mode bloquant (le script se met en pause jusqu'à la fin de l'envoi). Utilisez ftp_nb_put() lorsque vous souhaitez envoyer un fichier volumineux tout en affichant une progression, en traitant d'autres tâches, ou en évitant une requête longue et figée.

Qu'est-ce que ftp_nb_put() ?

La fonction ftp_nb_put() envoie un fichier vers un serveur FTP sans interrompre l'exécution du script. Elle accepte les paramètres suivants :

1. ftp_stream : L'identifiant de connexion retourné par ftp_connect() (un objet FTP\Connection en PHP 8.1+).
2. remote_file : Le chemin du fichier distant où le fichier sera envoyé.
3. local_file : Le chemin du fichier local à lire.
4. mode : Le mode de transfert, soit FTP_BINARY soit FTP_ASCII (requis avant PHP 7.3 ; optionnel et valant FTP_BINARY par défaut à partir de la version 7.3).
5. startpos (optionnel) : Le décalage en octets dans le fichier distant à partir duquel commencer l'écriture ; vaut 0 par défaut.

Contrairement à un envoi bloquant, ftp_nb_put() ne retourne pas simplement true/false. Elle retourne plutôt l'une des trois constantes entières suivantes :

En raison de ces valeurs de retour, ftp_nb_put() est presque toujours utilisée conjointement avec ftp_nb_continue() dans une boucle, comme indiqué ci-dessous.

Syntaxe de ftp_nb_put()

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

Syntaxe de ftp_nb_put()

int ftp_nb_put ( FTP\Connection $ftp_stream , string $remote_file , string $local_file , int $mode [, int $startpos = 0 ] )

La fonction ftp_nb_put() prend trois paramètres obligatoires (ftp_stream, remote_file et local_file) et un paramètre optionnel (startpos). Le paramètre mode est obligatoire et spécifie le mode de transfert : FTP_BINARY est recommandé pour la plupart des fichiers (images, archives, exécutables) afin d'éviter la corruption des fins de ligne, tandis que FTP_ASCII est utilisé pour les fichiers texte brut (bien que FTP_BINARY soit généralement plus sûr pour tous les types de fichiers). 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_put()

Pour utiliser la fonction ftp_nb_put(), vous établissez d'abord une connexion avec ftp_connect() et vous vous authentifiez avec ftp_login(). Vous démarrez ensuite l'envoi et le pilotez dans une boucle jusqu'à ce qu'il se termine :

Utilisation de ftp_nb_put()

<?php

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

// Login with your FTP credentials
if (!ftp_login($conn, 'username', 'password')) {
    die('Login failed.');
}

// Initiate an asynchronous FTP operation
$result = ftp_nb_put($conn, 'remote_file.txt', 'local_file.txt', FTP_BINARY);
if ($result === FTP_FAILED) {
    die('Upload failed.');
}

// 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);
}

if ($result === FTP_FINISHED) {
    echo "Upload completed successfully.\n";
}

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

Dans cet exemple, nous nous connectons au serveur FTP, nous nous connectons avec nos identifiants, et nous démarrons l'envoi avec ftp_nb_put(). Le premier appel retourne FTP_MOREDATA, nous entrons donc dans une boucle et appelons ftp_nb_continue() répétitivement pour envoyer le bloc suivant — le commentaire // Do something else est l'endroit où vous mettriez à jour une barre de progression ou traiteriez d'autres tâches. Lorsque la boucle se termine, nous vérifions FTP_FINISHED pour confirmer le succès, puis nous fermons la connexion avec ftp_close().

Remarque : Appelez toujours ftp_nb_continue() jusqu'à ce que le résultat ne soit plus FTP_MOREDATA. Si vous arrêtez prématurément, l'envoi reste incomplet sur le serveur.

Gestion des erreurs dans ftp_nb_put()

Il est important de gérer les erreurs correctement lors de l'utilisation de la fonction ftp_nb_put(). Si la fonction retourne FTP_FAILED, cela signifie que l'envoi a échoué. Voici un exemple de gestion des erreurs :

Gestion des erreurs dans ftp_nb_put()

<?php

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

if ($result === FTP_FAILED) {
    echo "Failed to upload file to remote server.\n";
}

while ($result === FTP_MOREDATA) {
    // Do something else while waiting for the FTP operation to complete
    $result = ftp_nb_continue($conn);
}

if ($result === FTP_FINISHED) {
    echo "Upload completed.\n";
}

ftp_close($conn);

En gérant les erreurs de manière appropriée et en vérifiant la valeur de retour de la fonction, vous pouvez garantir le succès de vos opérations FTP avec la fonction ftp_nb_put().

Fonctions associées

• ftp_put() — envoie un fichier en mode bloquant (plus simple, mais met le script en pause).
• ftp_nb_continue() — continue un transfert non bloquant démarré par ftp_nb_put().
• ftp_nb_fput() — envoi non bloquant depuis un descripteur de fichier déjà ouvert plutôt qu'un chemin.
• ftp_nb_get() — le pendant téléchargement de ftp_nb_put().

Conclusion

La fonction ftp_nb_put() envoie des fichiers vers un serveur FTP en mode non bloquant, permettant à votre script de continuer à effectuer d'autres tâches pendant que le transfert s'exécute en arrière-plan. La clé est de démarrer l'envoi, de boucler sur ftp_nb_continue() tant que le statut est FTP_MOREDATA, et de confirmer FTP_FINISHED (en gérant FTP_FAILED) avant de fermer la connexion. Avec une utilisation et une gestion des erreurs appropriées, c'est un outil précieux pour des transferts de fichiers réactifs dans vos projets PHP.

Remarque : Les fonctions ftp_nb_* sont considérées comme héritées dans le PHP moderne. Pour les nouveaux projets, envisagez d'utiliser cURL ou une bibliothèque HTTP asynchrone comme Guzzle pour de meilleures performances, une meilleure sécurité et un support de protocoles plus large.

Exercices pratiques