ftp_get_option()

Cos'è ftp_get_option()?

La funzione ftp_get_option() è una funzione built-in di PHP che recupera una singola opzione di runtime di una connessione FTP aperta. Un'opzione di runtime è un'impostazione configurabile che controlla il comportamento del client FTP — ad esempio, quanto tempo attende prima di andare in timeout, o se riprende automaticamente i trasferimenti interrotti. Queste impostazioni si leggono con ftp_get_option() e si modificano con la sua controparte ftp_set_option().

In genere si ricorre a ftp_get_option() quando è necessario ispezionare la configurazione attuale di una connessione prima di decidere come procedere — ad esempio, per registrare il timeout attivo o verificare che il ripristino automatico sia abilitato prima di avviare un download di grandi dimensioni.

La funzione accetta due parametri:

1. ftp — l'identificatore di connessione restituito da ftp_connect() (un oggetto FTP\Connection in PHP 8.1+, o una risorsa nelle versioni precedenti).
2. option — la costante che indica l'opzione da recuperare (ad esempio, FTP_TIMEOUT_SEC).

La funzione restituisce un valore mixed in base all'opzione richiesta — un intero per FTP_TIMEOUT_SEC, o un boolean per le opzioni flag. Se il nome dell'opzione è sconosciuto, PHP emette un avviso e la funzione restituisce false.

Sintassi di ftp_get_option()

La sintassi della funzione ftp_get_option() è la seguente:

Sintassi di ftp_get_option()

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

Entrambi i parametri sono obbligatori. Il parametro $ftp_stream è l'identificatore di connessione restituito da ftp_connect() (o da ftp_ssl_connect()), e $option è una delle costanti FTP_* predefinite descritte di seguito.

Opzioni disponibili in ftp_get_option()

ftp_get_option() riconosce le seguenti costanti di opzione. Il tipo di ritorno varia per ogni opzione, il che è importante quando si controlla il risultato:

Nota: FTP_USEPASVADDRESS è significativo solo in modalità passiva. FTP_LISTEN, che si può trovare in note precedenti, non è un'opzione valida per ftp_get_option() e interrogarlo produce un avviso e false.

Utilizzo di ftp_get_option()

Per utilizzare la funzione ftp_get_option(), è necessario prima stabilire una connessione al server FTP usando la funzione ftp_connect(). Ecco un esempio:

Utilizzo di 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);

In questo esempio, ci colleghiamo con ftp_connect(), ci autentichiamo con ftp_login(), quindi leggiamo due opzioni. Il valore predefinito di FTP_TIMEOUT_SEC su una connessione nuova è 90, quindi la prima riga stampa Current timeout: 90 seconds. Infine rilasciamo la connessione con ftp_close().

Gestione degli errori in ftp_get_option()

Poiché FTP_AUTOSEEK e FTP_USEPASVADDRESS possono restituire legittimamente il boolean false, non bisogna mai testare il risultato con un confronto debole == — un flag disabilitato sembrerebbe un errore. Usare l'operatore di identità stretta === per distinguere un vero errore da un valore false valido:

Gestione degli errori in 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);

Qui il controllo stretto === false distingue un vero errore di recupero da un'opzione il cui valore reale è 0 o false. Per le opzioni boolean come FTP_USEPASVADDRESS, catturare prima il risultato in una variabile e poi confrontarlo con === prima di considerarlo attivo o disattivo.

Funzioni correlate

• ftp_set_option() — modifica un'opzione di runtime (la controparte in scrittura di questa funzione).
• ftp_connect() — apre la connessione a cui si applicano queste opzioni.
• ftp_pasv() — attiva/disattiva la modalità passiva, che interagisce con FTP_USEPASVADDRESS.
• Panoramica FTP di PHP — tutte le funzioni FTP in un colpo d'occhio.

Conclusione

La funzione ftp_get_option() consente di leggere la configurazione di runtime di una connessione FTP aperta — in particolare il timeout di rete e i flag di ripristino automatico e indirizzo passivo. Ricordare che alcune opzioni restituiscono un boolean, quindi controllare sempre il risultato con === per evitare di confondere un false valido con un errore.

Esercizio