ftp_nb_continue()

Cos'è ftp_nb_continue()?

ftp_nb_continue() è una funzione built-in di PHP che riprende — ovvero continua — un trasferimento file FTP non bloccante avviato in precedenza. Il prefisso nb nel nome sta per non-blocking: invece di bloccare lo script fino al completamento dell'upload o del download dell'intero file, le funzioni FTP non bloccanti restituiscono il controllo dopo ogni blocco di dati, consentendo allo script di eseguire altre operazioni nel frattempo.

Questa pagina illustra i valori restituiti dalla funzione, il funzionamento del ciclo di trasferimento non bloccante, la gestione degli errori e gli errori comuni da evitare.

Come funzionano i trasferimenti non bloccanti

Un trasferimento normale come ftp_get() è bloccante: PHP attende il completamento dell'intero file prima di eseguire la riga successiva. La famiglia non bloccante — ftp_nb_get(), ftp_nb_put(), ftp_nb_fget() e ftp_nb_fput() — avvia il trasferimento e restituisce il controllo immediatamente. Dopodiché si chiama ftp_nb_continue() ripetutamente per avanzare il trasferimento un blocco alla volta, finché non segnala il completamento.

La funzione restituisce una delle tre costanti seguenti:

Nota: la funzione di avvio (ftp_nb_get() ecc.) restituisce lo stesso insieme di costanti, quindi la logica del ciclo deve tenere conto della possibilità che il trasferimento si completi già alla prima chiamata.

Sintassi di ftp_nb_continue()

ftp_nb_continue(resource $ftp): int

Accetta un unico parametro, $ftp: l'identificatore di connessione restituito da ftp_connect() o ftp_ssl_connect().

PHP 8.1+: la connessione è ora un oggetto FTP\Connection anziché una resource, ma il codice non deve essere modificato — si passa semplicemente il valore restituito da ftp_connect().

Utilizzo di ftp_nb_continue()

Per prima cosa si avvia un trasferimento non bloccante, poi lo si porta a termine con un ciclo:

<?php

// Open the connection and log in
$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'username', 'password');
ftp_pasv($ftp, true); // passive mode is usually required behind firewalls

// Start a non-blocking download: local_file <- remote_file
$state = ftp_nb_get($ftp, 'local_file.txt', 'remote_file.txt', FTP_BINARY);

// Drive the transfer forward until it finishes or fails
while ($state === FTP_MOREDATA) {
    // You can do other work here while the file streams in
    $state = ftp_nb_continue($ftp);
}

if ($state === FTP_FINISHED) {
    echo "Download complete.\n";
} else {
    echo "Download failed.\n";
}

ftp_close($ftp);

Si noti l'ordine degli argomenti di ftp_nb_get(): è (connessione, file_locale, file_remoto, modalità) — la destinazione locale precede la sorgente remota.

Gestione degli errori

Verificare sempre il valore restituito a ogni iterazione. Se ftp_nb_continue() restituisce FTP_FAILED, il trasferimento è interrotto e occorre fermarsi e segnalarlo anziché continuare a ciclare indefinitamente:

<?php

$state = ftp_nb_get($ftp, 'local_file.txt', 'remote_file.txt', FTP_BINARY);

while ($state === FTP_MOREDATA) {
    $state = ftp_nb_continue($ftp);
}

switch ($state) {
    case FTP_FINISHED:
        echo "Transfer succeeded.\n";
        break;
    case FTP_FAILED:
        echo "Transfer failed.\n";
        break;
}

Poiché la condizione del ciclo è === FTP_MOREDATA, il ciclo termina automaticamente sia per FTP_FINISHED che per FTP_FAILED — il switch successivo indica quale dei due si è verificato.

Errori comuni

• Dimenticare di controllare il valore restituito dalla funzione di avvio. Un file piccolo può completarsi durante ftp_nb_get() stesso, restituendo FTP_FINISHED prima ancora che il ciclo venga eseguito. Assegnare quel valore restituito a $state (come sopra) gestisce questo caso correttamente.
• Chiamare ftp_nb_continue() senza un trasferimento attivo. Funziona solo mentre un'operazione non bloccante è in sospeso; in caso contrario restituisce FTP_FAILED.
• Un ciclo stretto e vuoto. Lo scopo principale dell'FTP non bloccante è eseguire lavoro utile tra le chiamate. Un ciclo while vuoto si limita ad attendere attivamente e non offre alcun vantaggio rispetto al bloccante ftp_get().
• Modalità passiva. Dietro un firewall o NAT di solito è necessario impostare ftp_pasv() a true prima di avviare il trasferimento.

Conclusione

ftp_nb_continue() riprende un trasferimento FTP non bloccante avviato con ftp_nb_get(), ftp_nb_put(), ftp_nb_fget() o ftp_nb_fput(). Chiamarla in un ciclo finché restituisce FTP_MOREDATA, fermarsi su FTP_FINISHED e gestire FTP_FAILED — così lo script rimane reattivo mentre i file vengono trasferiti in background.

Pratica