ftp_set_option()

La funzione ftp_set_option() configura il comportamento di runtime per una connessione FTP già aperta in PHP. Consente di regolare il funzionamento del client FTP — timeout di connessione, indirizzi in modalità passiva e se i download eseguano automaticamente la ricerca dell'offset durante la ripresa — senza dover chiudere e riaprire la connessione.

Questa pagina spiega cosa fa ciascuna opzione, quando usarla e come impostarle in modo sicuro. Si presuppone che tu abbia già una connessione aperta tramite ftp_connect() (o ftp_ssl_connect()) e che tu abbia effettuato l'accesso con ftp_login().

Sintassi

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

La funzione restituisce true in caso di successo, oppure false se l'opzione non può essere impostata (ad esempio quando $value ha il tipo errato per l'$option scelta).

Nota: In PHP 8.1+ il primo argomento è un oggetto FTP\Connection. In PHP 8.0 e versioni precedenti è una resource restituita da ftp_connect(). Il nome della funzione e il comportamento sono altrimenti identici.

Utilizzo di base

Apri una connessione, effettua il login, poi imposta l'opzione. L'impostazione delle opzioni avviene solitamente subito dopo il login, prima di iniziare il trasferimento dei file, in modo che ogni trasferimento utilizzi il nuovo comportamento.

<?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);

Qui ci connettiamo con ftp_connect(), eseguiamo l'autenticazione con ftp_login(), abbassamo il timeout di rete a 30 secondi con ftp_set_option(), e infine chiudiamo la connessione con ftp_close().

Opzioni disponibili

ftp_set_option() accetta le seguenti costanti di opzione:

FTP_TIMEOUT_SEC e FTP_USEPASVADDRESS sono le due opzioni che si modificano più spesso nel codice reale: la prima quando i trasferimenti vanno in timeout, la seconda quando la modalità passiva fallisce dietro un firewall.

Puoi leggere il valore corrente di qualsiasi opzione con ftp_get_option().

Disabilitare l'auto-seek

Un motivo comune per chiamare ftp_set_option() è disattivare FTP_AUTOSEEK. Per impostazione predefinita, la ripresa di un download con un offset diverso da zero cerca il file locale. Se vuoi che ogni download sovrascriva dal byte zero, disabilitalo:

<?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);

Gestione degli errori

ftp_set_option() restituisce false (ed emette un avviso) quando il valore non corrisponde all'opzione — ad esempio, passando una string dove è atteso un int. Controlla il valore restituito in modo che un'opzione ignorata silenziosamente non ti sorprenda in seguito:

<?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);

Lavora sempre con una connessione attiva: passare una connessione chiusa o non valida genera un avviso anziché un false pulito, quindi imposta le opzioni prima di chiamare ftp_close().

Conclusione

ftp_set_option() regola il comportamento di una connessione FTP aperta — in modo più utile il timeout di rete e la gestione degli indirizzi in modalità passiva dietro NAT. Imposta le opzioni immediatamente dopo ftp_login(), verifica il valore restituito e usa ftp_get_option() per confermare cosa è attualmente in vigore. Per il flusso FTP completo, consulta la panoramica PHP FTP.

Pratica