ftp_nb_get()

Comprendere la funzione PHP ftp_nb_get()

La funzione ftp_nb_get() scarica un file da un server FTP in modalità non bloccante. A differenza della sua controparte bloccante ftp_get(), che sospende lo script fino al completamento del trasferimento dell'intero file, ftp_nb_get() restituisce il controllo al programma quasi immediatamente, consentendoti di svolgere altre operazioni mentre il download avviene in background.

Questa pagina spiega quando scegliere la variante non bloccante, illustra ogni parametro e valore restituito, e mostra un pattern di utilizzo completo con ftp_nb_continue().

Quando utilizzare la modalità non bloccante

La sigla "nb" nel nome sta per non-blocking (non bloccante). Scegli ftp_nb_get() invece di ftp_get() quando:

• Vuoi visualizzare l'avanzamento o mantenere un'interfaccia utente reattiva mentre viene scaricato un file di grandi dimensioni.
• Hai bisogno di alternare altre operazioni (logging, invio di heartbeat, elaborazione di dati già scaricati) durante il trasferimento.
• Vuoi applicare la tua logica di timeout o cancellazione nel ciclo di polling.

Per un semplice "scarica questo file e aspetta", ftp_get() semplice è più diretto ed è la scelta migliore. Il compromesso è che la modalità non bloccante richiede di gestire il trasferimento manualmente in un ciclo con ftp_nb_continue().

Cos'è ftp_nb_get()?

La funzione ftp_nb_get() avvia un download asincrono di file. Richiede quattro parametri:

1. ftp_stream: L'identificatore di connessione restituito da ftp_connect().
2. local_file: Il percorso del file locale dove verrà salvato il file scaricato.
3. remote_file: Il percorso del file remoto sul server FTP.
4. mode: La modalità di trasferimento, FTP_ASCII o FTP_BINARY.

Accetta anche un quinto parametro opzionale, resumepos, che specifica la posizione nel file remoto da cui iniziare il download (il valore predefinito è 0).

La funzione restituisce una delle tre costanti:

Poiché la funzione può restituire il controllo prima che il download sia terminato, quasi sempre si abbina a ftp_nb_continue() in un ciclo che viene eseguito finché il risultato è FTP_MOREDATA.

Sintassi di ftp_nb_get()

La sintassi della funzione ftp_nb_get() è la seguente:

Sintassi di ftp_nb_get()

int ftp_nb_get ( resource $ftp_stream , string $local_file , string $remote_file , int $mode [, int $resumepos = 0 ] )

La funzione ftp_nb_get() accetta quattro parametri obbligatori (ftp_stream, local_file, remote_file e mode) e un parametro opzionale (resumepos). Il parametro ftp_stream è l'identificatore di connessione restituito da ftp_connect(). Il parametro local_file è il percorso del file locale dove verrà salvato il file scaricato. Il parametro remote_file è il percorso del file remoto sul server FTP. Il parametro mode specifica la modalità di trasferimento, FTP_ASCII o FTP_BINARY. Il parametro resumepos specifica la posizione nel file remoto da cui iniziare il download. Per impostazione predefinita, resumepos è impostato su 0, il che significa che il download inizierà dall'inizio del file.

Utilizzo di ftp_nb_get()

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

Utilizzo di ftp_nb_get()

<?php

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

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

// Initiate an asynchronous FTP operation
$result = ftp_nb_get($conn, 'local_file.txt', 'remote_file.txt', FTP_BINARY);

if ($result === FTP_FAILED) {
    echo "Failed to download file from remote server.\n";
} else {
    // Continue the asynchronous FTP operation
    while ($result === FTP_MOREDATA) {
        // Do something else while waiting for the FTP operation to complete
        $result = ftp_nb_continue($conn);
    }
}

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

In questo esempio, stabiliamo una connessione al server FTP usando ftp_connect(). Poi effettuiamo il login con le credenziali FTP tramite ftp_login(). Avviamo un'operazione FTP asincrona con ftp_nb_get(). Continuiamo l'operazione usando ftp_nb_continue() all'interno di un ciclo che controlla FTP_MOREDATA e infine chiudiamo la connessione FTP.

Riprendere un download interrotto

Il quinto parametro opzionale, resumepos, ti consente di continuare un file parzialmente scaricato invece di ricominciare dall'inizio. Passa l'offset in byte da cui riprendere — tipicamente la dimensione del file già presente su disco:

Riprendere un download con resumepos

<?php

$local = 'big-archive.zip';

// If a partial file already exists, resume from where it left off.
$resumePos = file_exists($local) ? filesize($local) : 0;

$result = ftp_nb_get($conn, $local, 'big-archive.zip', FTP_BINARY, $resumePos);

while ($result === FTP_MOREDATA) {
    $result = ftp_nb_continue($conn);
}

Questo è particolarmente utile per file di grandi dimensioni su connessioni inaffidabili, quando non si vuole riscaricare dati già ottenuti.

Gestione degli errori in ftp_nb_get()

Controlla sempre il valore restituito. ftp_nb_get() restituisce FTP_FAILED quando non riesce ad avviare (o continuare) il trasferimento, e anche ftp_nb_continue() può restituire FTP_FAILED a metà trasferimento. Gestisci entrambi i casi:

Gestione degli errori in ftp_nb_get()

<?php

$conn = ftp_connect('ftp.example.com');

if ($conn === false || !ftp_login($conn, 'username', 'password')) {
    exit("Could not connect or log in to the FTP server.\n");
}

$result = ftp_nb_get($conn, 'local_file.txt', 'remote_file.txt', FTP_BINARY);

// Drive the transfer to completion, watching for failure at every step.
while ($result === FTP_MOREDATA) {
    $result = ftp_nb_continue($conn);
}

if ($result === FTP_FINISHED) {
    echo "File downloaded successfully.\n";
} else {
    echo "Failed to download file from remote server.\n";
}

ftp_close($conn);

Verificando separatamente la connessione, il login e lo stato finale del trasferimento, puoi individuare esattamente dove un'operazione FTP è andata storta.

Funzioni correlate

• ftp_get() — la versione bloccante che scarica un file e attende il completamento.
• ftp_nb_continue() — continua un trasferimento non bloccante avviato da ftp_nb_get().
• ftp_nb_fget() — come ftp_nb_get(), ma scrive su un puntatore a file aperto invece di un percorso.
• ftp_connect() e ftp_login() — stabiliscono e autenticano la sessione FTP.
• ftp_close() — chiude la connessione al termine delle operazioni.

Conclusione

La funzione ftp_nb_get() scarica file da un server FTP in modalità non bloccante, permettendo allo script di rimanere reattivo durante il trasferimento. Abbinala a ftp_nb_continue() in un ciclo, controlla il valore restituito rispetto a FTP_FINISHED e FTP_FAILED, e usa resumepos per recuperare i download interrotti.

Pratica