ftp_fput()

Qu'est-ce que ftp_fput() ?

La fonction ftp_fput() est une fonction PHP intégrée qui envoie un fichier vers le serveur FTP. La fonction accepte cinq paramètres :

1. ftp_stream : L'identifiant de connexion retourné par la fonction ftp_connect().
2. remote_file : Le nom du fichier distant vers lequel le fichier doit être envoyé.
3. local_file : Une ressource de gestion de fichier ouverte avec fopen() qui pointe vers le fichier local à envoyer.
4. mode (optionnel) : Le mode de transfert (FTP_ASCII ou FTP_BINARY). Par défaut FTP_ASCII.
5. startpos (optionnel) : La position de départ dans le fichier distant pour l'envoi. Par défaut 0.

La fonction retourne une valeur boolean. Si la fonction réussit à envoyer le fichier, elle retourne true. Sinon, elle retourne false.

Quand utiliser ftp_fput() plutôt que ftp_put()

ftp_put() prend un chemin de fichier local sous forme de string et ouvre le fichier pour vous. ftp_fput() prend à la place un handle de fichier déjà ouvert. Optez pour ftp_fput() dans les cas suivants :

• Les données à envoyer ne sont pas un fichier ordinaire sur le disque — par exemple un flux temporaire créé avec php://temp, ou la sortie d'une autre ressource déjà ouverte.
• Vous avez besoin d'un contrôle précis sur la position de lecture (combiné au paramètre startpos, vous pouvez reprendre un envoi interrompu).
• Vous avez déjà ouvert le handle pour une autre raison et souhaitez éviter d'ouvrir le même fichier deux fois.

Si vous voulez simplement envoyer un fichier existant par son nom, ftp_put() est plus simple. Pour les envois non bloquants (asynchrones), voir ftp_nb_fput().

Syntaxe de ftp_fput()

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

Syntaxe de ftp_fput()

bool ftp_fput ( resource $ftp_stream , string $remote_file , resource $local_file [, int $mode = FTP_ASCII [, int $startpos = 0 ]] )

Utilisation de ftp_fput()

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

Utilisation de ftp_fput() en PHP

<?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.");
}

// Open the local file
$local_file = fopen('/local/directory/local_file.txt', 'r');
if (!$local_file) {
    die("Could not open local file.");
}

// Upload the file to the remote FTP server
if (ftp_fput($conn, 'remote_file.txt', $local_file, FTP_ASCII)) {
    echo "File uploaded successfully.\n";
} else {
    echo "Failed to upload the file.\n";
}

// Close the file handle and FTP connection
fclose($local_file);
ftp_close($conn);

Dans cet exemple, nous établissons une connexion au serveur FTP à l'aide de la fonction ftp_connect() et vérifions qu'elle a réussi. Nous nous connectons ensuite avec nos identifiants FTP via ftp_login() et vérifions les erreurs. Puis nous ouvrons le fichier local avec fopen() pour obtenir le handle de fichier requis. Enfin, nous envoyons le fichier vers le serveur FTP distant avec ftp_fput() et fermons à la fois le handle de fichier et la connexion FTP avec ftp_close().

Choisir le mode de transfert : FTP_ASCII vs FTP_BINARY

Le paramètre mode contrôle la façon dont les octets sont transférés et a plus d'importance qu'il n'y paraît :

• FTP_BINARY transfère le fichier octet par octet, sans modification. Utilisez-le pour les images, les archives, les exécutables, les PDFs — tout ce qui n'est pas du texte brut. C'est la valeur par défaut sûre pour presque tout.
• FTP_ASCII traduit les fins de ligne entre les plateformes locale et distante (par ex. \n ↔ \r\n). Il n'est approprié que pour les fichiers texte brut ; l'utiliser sur des données binaires corrompra silencieusement le fichier.

Lorsque vous ouvrez le handle local, faites correspondre le mode fopen() au transfert : utilisez 'rb' (lecture binaire) avec FTP_BINARY pour que PHP n'altère pas les octets en chemin :

<?php

$local_file = fopen('/local/directory/photo.jpg', 'rb');
ftp_fput($conn, 'photo.jpg', $local_file, FTP_BINARY);
fclose($local_file);

Gestion des erreurs dans ftp_fput()

Il est important de gérer correctement les erreurs lors de l'utilisation de la fonction ftp_fput(). Si la fonction retourne false, cela signifie que le fichier n'a pas pu être envoyé pour une raison quelconque. Voici un exemple de gestion des erreurs :

Gestion des erreurs dans ftp_fput()

<?php

// Assuming $conn is already established via ftp_connect() and ftp_login()
$local_file = fopen('/local/directory/local_file.txt', 'rb');

if ($local_file === false) {
    echo "Could not open the local file.\n";
} elseif (ftp_fput($conn, 'remote_file.txt', $local_file, FTP_BINARY)) {
    echo "File uploaded successfully.\n";
    fclose($local_file);
} else {
    echo "Failed to upload the file.\n";
    fclose($local_file);
}

Remarquez l'ordre des vérifications : nous confirmons d'abord que fopen() a retourné un handle valide, puis appelons ftp_fput(). Appeler fclose() sur un handle false (ce qui se produit si l'exemple original omet la vérification de l'ouverture) émet un avertissement ; nous ne fermons donc le handle que dans les branches où il a effectivement été ouvert. Cela empêche le message de succès de s'afficher lorsque l'envoi n'a pas eu lieu.

Pièges courants

• Passer un chemin au lieu d'un handle. ftp_fput() attend la ressource retournée par fopen(), et non une string de nom de fichier. Si vous avez un chemin, utilisez plutôt ftp_put().
• Mauvais mode de transfert. Envoyer un fichier binaire avec FTP_ASCII le corrompt. En cas de doute, utilisez FTP_BINARY.
• Ne pas fermer le handle. Appelez toujours fclose() une fois le transfert terminé pour libérer la ressource.
• Mode passif. Derrière un pare-feu, de nombreux serveurs exigent le mode passif. Appelez ftp_pasv($conn, true) après la connexion si les envois se bloquent.

Conclusion

La fonction ftp_fput() envoie un fichier vers un serveur FTP à partir d'un handle de fichier ouvert, ce qui en fait le bon choix lorsque vos données résident déjà dans un flux plutôt qu'à un chemin fixe sur le disque. Associez-la au bon mode de transfert, vérifiez les valeurs de retour de fopen() et de ftp_fput(), fermez vos handles, et elle fonctionnera de manière fiable dans vos projets PHP.

Pratique