ftp_get_option()

Qu'est-ce que ftp_get_option() ?

La fonction ftp_get_option() est une fonction PHP intégrée qui récupère une seule option d'exécution d'une connexion FTP ouverte. Une option d'exécution est un paramètre configurable qui contrôle le comportement du client FTP — par exemple, combien de temps il attend avant d'expirer, ou s'il reprend automatiquement les transferts interrompus. Vous lisez ces paramètres avec ftp_get_option() et vous les modifiez avec sa contrepartie ftp_set_option().

Vous faites généralement appel à ftp_get_option() lorsque vous devez inspecter la configuration actuelle d'une connexion avant de décider quoi faire ensuite — par exemple, journaliser le délai d'attente actif, ou confirmer que la reprise automatique est activée avant de démarrer un téléchargement volumineux.

La fonction prend deux paramètres :

1. ftp — l'identifiant de connexion retourné par ftp_connect() (un objet FTP\Connection en PHP 8.1+, ou une ressource dans les versions antérieures).
2. option — la constante désignant l'option à récupérer (par exemple, FTP_TIMEOUT_SEC).

La fonction retourne une valeur mixte selon l'option interrogée — un entier pour FTP_TIMEOUT_SEC, ou un boolean pour les options booléennes. Si le nom de l'option est inconnu, PHP émet un avertissement et la fonction retourne false.

Syntaxe de ftp_get_option()

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

Syntaxe de ftp_get_option()

mixed ftp_get_option ( FTP\Connection|resource $ftp_stream , int $option )

Les deux paramètres sont obligatoires. Le paramètre $ftp_stream est l'identifiant de connexion retourné par ftp_connect() (ou ftp_ssl_connect()), et $option est l'une des constantes FTP_* prédéfinies décrites ci-dessous.

Options disponibles dans ftp_get_option()

ftp_get_option() reconnaît les constantes d'option suivantes. Le type de retour diffère selon l'option, ce qui est important lors de la vérification du résultat :

Remarque : FTP_USEPASVADDRESS n'est significatif qu'en mode passif. FTP_LISTEN, que vous pouvez rencontrer dans d'anciennes notes, n'est pas une option valide pour ftp_get_option() et l'interroger produit un avertissement et false.

Utilisation de ftp_get_option()

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

Utilisation de ftp_get_option()

<?php

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

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

// Retrieve the current timeout (in seconds)
$timeout = ftp_get_option($conn, FTP_TIMEOUT_SEC);
echo "Current timeout: {$timeout} seconds\n"; // Default: 90 seconds

// Check whether passive-address rewriting is enabled
$usePasv = ftp_get_option($conn, FTP_USEPASVADDRESS);
echo "Use PASV address: " . ($usePasv ? "yes" : "no") . "\n";

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

Dans cet exemple, nous nous connectons avec ftp_connect(), nous nous authentifions avec ftp_login(), puis nous lisons deux options. La valeur par défaut de FTP_TIMEOUT_SEC sur une nouvelle connexion est 90, donc la première ligne affiche Current timeout: 90 seconds. Enfin, nous libérons la connexion avec ftp_close().

Gestion des erreurs dans ftp_get_option()

Étant donné que FTP_AUTOSEEK et FTP_USEPASVADDRESS peuvent légitimement retourner le boolean false, ne testez jamais le résultat avec un == non strict — un indicateur désactivé ressemblerait à un échec. Utilisez l'opérateur d'identité strict === pour distinguer une véritable erreur d'une valeur false valide :

Gestion des erreurs dans ftp_get_option()

<?php

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

$timeout = ftp_get_option($conn, FTP_TIMEOUT_SEC);

if ($timeout === false) {
    // The option name was invalid, or the connection is not usable
    echo "Failed to retrieve the option.\n";
} elseif ($timeout > 0) {
    echo "Timeout is set to {$timeout} seconds.\n";
} else {
    echo "No timeout is set.\n";
}

ftp_close($conn);

Ici, la vérification stricte === false distingue un véritable échec de récupération d'une option dont la valeur réelle est 0 ou false. Pour les options booléennes telles que FTP_USEPASVADDRESS, capturez d'abord le résultat dans une variable, puis comparez avec === avant de le traiter comme activé ou désactivé.

Fonctions connexes

• ftp_set_option() — modifier une option d'exécution (la contrepartie en écriture de cette fonction).
• ftp_connect() — ouvrir la connexion à laquelle ces options s'appliquent.
• ftp_pasv() — basculer en mode passif, qui interagit avec FTP_USEPASVADDRESS.
• Vue d'ensemble FTP PHP — toutes les fonctions FTP en un coup d'œil.

Conclusion

La fonction ftp_get_option() vous permet de lire la configuration d'exécution d'une connexion FTP ouverte — principalement le délai d'expiration réseau et les indicateurs de reprise automatique et d'adresse passive. N'oubliez pas que certaines options retournent un boolean, alors vérifiez toujours le résultat avec === pour éviter de confondre un false valide avec une erreur.

Pratique