ftp_set_option()

La fonction ftp_set_option() configure le comportement d'exécution d'une connexion FTP déjà ouverte en PHP. Elle vous permet d'ajuster le comportement du client FTP — délais d'attente réseau, adressage en mode passif, et si les téléchargements effectuent une recherche automatique lors de la reprise — sans fermer ni rétablir la connexion.

Cette page explique ce que chaque option fait, quand vous en aurez besoin, et comment les définir en toute sécurité. Elle suppose que vous disposez déjà d'une connexion ouverte via ftp_connect() (ou ftp_ssl_connect()) et que vous êtes authentifié avec ftp_login().

Syntaxe

ftp_set_option(FTP\Connection $ftp, int $option, mixed $value): bool

La fonction retourne true en cas de succès, ou false si l'option n'a pas pu être définie (par exemple, lorsque $value a un type incorrect pour l'option $option choisie).

Remarque : En PHP 8.1+, le premier argument est un objet FTP\Connection. Avec PHP 8.0 et versions antérieures, c'est une resource retournée par ftp_connect(). Le nom de la fonction et son comportement restent sinon identiques.

Utilisation de base

Ouvrez une connexion, authentifiez-vous, puis définissez l'option. La définition des options se fait généralement juste après la connexion, avant de commencer à transférer des fichiers, afin que chaque transfert utilise le nouveau comportement.

<?php

// Open a connection to the FTP server
$ftp = ftp_connect('ftp.example.com');

if (!$ftp) {
    die('Could not connect to FTP server.');
}

// Authenticate
ftp_login($ftp, 'username', 'password');

// Abort any network operation that stalls for more than 30 seconds
ftp_set_option($ftp, FTP_TIMEOUT_SEC, 30);

// ... transfers happen here ...

ftp_close($ftp);

Ici, nous nous connectons avec ftp_connect(), nous nous authentifions avec ftp_login(), nous réduisons le délai d'attente réseau à 30 secondes avec ftp_set_option(), et enfin nous fermons la connexion avec ftp_close().

Options disponibles

ftp_set_option() accepte les constantes d'option suivantes :

FTP_TIMEOUT_SEC et FTP_USEPASVADDRESS sont les deux options que vous ajusterez le plus souvent dans du code réel : la première lorsque les transferts expirent, la seconde lorsque le mode passif échoue derrière un pare-feu.

Vous pouvez lire la valeur actuelle de l'une de ces options avec ftp_get_option().

Désactiver l'auto-seek

L'une des raisons courantes d'appeler ftp_set_option() est de désactiver FTP_AUTOSEEK. Par défaut, la reprise d'un téléchargement avec un offset non nul effectue une recherche dans le fichier local. Si vous souhaitez que chaque téléchargement écrase depuis l'octet zéro, désactivez-le :

<?php

$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'username', 'password');

// Force full transfers instead of resuming from an offset
ftp_set_option($ftp, FTP_AUTOSEEK, false);

ftp_close($ftp);

Gestion des échecs

ftp_set_option() retourne false (et émet un avertissement) lorsque la valeur ne correspond pas à l'option — par exemple, en passant une string là où un int est attendu. Vérifiez la valeur de retour afin qu'une option silencieusement ignorée ne vous surprenne pas plus tard :

<?php

$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'username', 'password');

if (!ftp_set_option($ftp, FTP_TIMEOUT_SEC, 30)) {
    echo "Failed to set the FTP timeout option.\n";
}

ftp_close($ftp);

Travaillez toujours avec une connexion active : passer une connexion fermée ou invalide produit un avertissement plutôt qu'un false propre. Définissez donc vos options avant d'appeler ftp_close().

Conclusion

ftp_set_option() ajuste le comportement d'une connexion FTP ouverte — notamment son délai d'attente réseau et la gestion des adresses en mode passif derrière un NAT. Définissez les options immédiatement après ftp_login(), vérifiez la valeur de retour, et utilisez ftp_get_option() pour confirmer ce qui est actuellement en vigueur. Pour le flux FTP complet, consultez l'aperçu PHP FTP.

Pratique