ftp_put()

La fonction PHP ftp_put()

ftp_put() est une fonction PHP intégrée qui envoie un fichier local vers un serveur FTP distant. Elle est le pendant d'envoi de ftp_get(), qui télécharge un fichier distant vers votre machine. Cette page couvre la signature, les modes de transfert essentiels, un flux de travail complet, la gestion des erreurs et les pièges les plus courants en production.

Vous utilisez ftp_put() après avoir ouvert une connexion avec ftp_connect() et vous être authentifié avec ftp_login().

Syntaxe

ftp_put(
    FTP\Connection $ftp,
    string $remote_filename,
    string $local_filename,
    int $mode = FTP_BINARY
): bool

Retourne true en cas de succès et false en cas d'échec.

Note de version : Avant PHP 8.1, le premier argument était une resource retournée par ftp_connect(). À partir de PHP 8.1, c'est un objet FTP\Connection. Votre code ne change pas — vous passez toujours ce que retourne ftp_connect() — mais les vérifications is_resource() ne fonctionnent plus dessus.

Mode binaire vs. mode ASCII

Choisir le mauvais mode est la cause la plus fréquente du problème « le transfert a réussi mais le fichier est corrompu » :

• FTP_BINARY transfère les octets tels quels. Utilisez-le par défaut pour tout — images, archives, PDF, exécutables, et même les fichiers texte en pratique.
• FTP_ASCII réécrit les fins de ligne (\n ↔ \r\n) pour correspondre à la plateforme de destination. N'est pertinent que pour le texte brut, et il détruira silencieusement tout fichier binaire. En cas de doute, restez sur FTP_BINARY.

Un envoi complet

Vérifiez toujours les valeurs de retour de chaque appel FTP plutôt que de supposer qu'une étape a réussi :

<?php

// 1. Open a connection (false on failure)
$ftp = ftp_connect('ftp.example.com');
if ($ftp === false) {
    exit("Could not connect to FTP server.\n");
}

// 2. Authenticate
if (!ftp_login($ftp, 'username', 'password')) {
    ftp_close($ftp);
    exit("FTP login failed.\n");
}

// 3. Behind a firewall/NAT? Passive mode is almost always required.
ftp_pasv($ftp, true);

// 4. Upload: local file -> remote path, binary mode
$ok = ftp_put($ftp, '/public_html/index.html', './build/index.html', FTP_BINARY);

echo $ok
    ? "Upload succeeded.\n"
    : "Upload failed.\n";

// 5. Always close
ftp_close($ftp);

Notez l'ordre des arguments : le chemin distant en premier, la source locale en second — l'inverse de ce que beaucoup de personnes attendent. Les inverser fait tenter à PHP de lire un fichier local inexistant et l'appel échoue.

Gestion des erreurs

ftp_put() retourne false et émet un avertissement PHP en cas d'échec. Convertissez cela en un résultat clair et exploitable plutôt que de laisser un avertissement parasite s'infiltrer dans votre sortie :

<?php

$remote = '/public_html/index.html';
$local  = './build/index.html';

// Catch the "no such local file" case before touching the network.
if (!is_readable($local)) {
    exit("Local file '$local' is missing or unreadable.\n");
}

if (!ftp_put($ftp, $remote, $local, FTP_BINARY)) {
    // Common causes: wrong remote directory, no write permission,
    // disk quota exceeded, or passive mode not enabled.
    echo "Failed to upload '$local' to '$remote'.\n";
} else {
    echo "Uploaded '$local' to '$remote'.\n";
}

ftp_close($ftp);

Causes d'échec courantes

• Ordre des arguments incorrect — chemin distant et chemin local inversés.
• Mode passif non activé — la plupart des serveurs derrière un NAT nécessitent ftp_pasv($ftp, true) après la connexion.
• Répertoire distant manquant — ftp_put() ne crée pas les dossiers ; utilisez ftp_mkdir() au préalable.
• Aucune permission d'écriture ou quota dépassé côté serveur.
• Mauvais mode de transfert corrompant un fichier binaire (utilisez FTP_BINARY).

Envoi depuis un flux ouvert

Si vos données sont déjà un handle de fichier ouvert (ou proviennent d'un wrapper de flux plutôt que d'un chemin sur disque), utilisez ftp_fput() à la place — il prend une ressource de flux en lieu et place d'un nom de fichier local.

Conclusion

ftp_put() envoie un fichier local vers un serveur FTP distant. Retenez les trois points qui causent la plupart des problèmes : passez le chemin distant en premier, conservez FTP_BINARY sauf si vous avez une raison précise d'utiliser l'ASCII, et vérifiez chaque valeur de retour. Pour des transferts non bloquants qui ne figent pas votre script, consultez ftp_nb_put().

Pratique