ftp_nb_put()

Comprendere la funzione PHP ftp_nb_put()

La funzione ftp_nb_put() è una funzione PHP integrata che carica un file su un server FTP in modalità non bloccante. "Non bloccante" significa che la chiamata restituisce il controllo immediatamente dopo aver avviato il trasferimento, invece di attenderne il completamento, così lo script può continuare a svolgere altre operazioni mentre i dati viaggiano sulla rete. Questa guida ne illustra i parametri, la sintassi, l'utilizzo e la gestione degli errori, in modo da poterla integrare efficacemente nei progetti PHP.

La funzione complementare è ftp_put(), che carica in modalità bloccante (lo script si mette in pausa fino al completamento del caricamento). Usa ftp_nb_put() quando vuoi caricare un file di grandi dimensioni mostrando lo stato di avanzamento, elaborando altri compiti o evitando una richiesta lunga e bloccata.

Cos'è ftp_nb_put()?

La funzione ftp_nb_put() carica un file su un server FTP senza interrompere l'esecuzione dello script. Accetta i seguenti parametri:

1. ftp_stream: L'identificatore di connessione restituito da ftp_connect() (un oggetto FTP\Connection in PHP 8.1+).
2. remote_file: Il percorso del file remoto in cui verrà caricato il file.
3. local_file: Il percorso del file locale da leggere.
4. mode: La modalità di trasferimento, FTP_BINARY o FTP_ASCII (obbligatorio prima di PHP 7.3; opzionale con valore predefinito FTP_BINARY dalla versione 7.3 in poi).
5. startpos (opzionale): L'offset in byte nel file remoto da cui iniziare la scrittura; il valore predefinito è 0.

A differenza di un caricamento bloccante, ftp_nb_put() non restituisce un semplice true/false. Restituisce invece una delle tre costanti intere seguenti:

A causa di questi valori di ritorno, ftp_nb_put() viene quasi sempre usata insieme a ftp_nb_continue() in un ciclo, come mostrato di seguito.

Sintassi di ftp_nb_put()

La sintassi della funzione ftp_nb_put() è la seguente:

Sintassi di ftp_nb_put()

int ftp_nb_put ( FTP\Connection $ftp_stream , string $remote_file , string $local_file , int $mode [, int $startpos = 0 ] )

La funzione ftp_nb_put() richiede tre parametri obbligatori (ftp_stream, remote_file e local_file) e un parametro opzionale (startpos). Il parametro mode è obbligatorio e specifica la modalità di trasferimento: FTP_BINARY è consigliato per la maggior parte dei file (immagini, archivi, eseguibili) per evitare la corruzione dei terminatori di riga, mentre FTP_ASCII viene usato per i file di testo normale (anche se FTP_BINARY è generalmente più sicuro per tutti i tipi di file). Il parametro startpos specifica la posizione nel file remoto da cui iniziare il caricamento. Per impostazione predefinita, startpos è impostato su 0, il che significa che il caricamento inizierà dall'inizio del file.

Utilizzo di ftp_nb_put()

Per utilizzare la funzione ftp_nb_put(), occorre prima stabilire una connessione con ftp_connect() e autenticarsi con ftp_login(). Poi si avvia il caricamento e lo si porta avanti in un ciclo fino al completamento:

Utilizzo di ftp_nb_put()

<?php

// Set up an FTP connection
$conn = ftp_connect('ftp.example.com');
if (!$conn) {
    die('Could not connect to FTP server.');
}

// Login with your FTP credentials
if (!ftp_login($conn, 'username', 'password')) {
    die('Login failed.');
}

// Initiate an asynchronous FTP operation
$result = ftp_nb_put($conn, 'remote_file.txt', 'local_file.txt', FTP_BINARY);
if ($result === FTP_FAILED) {
    die('Upload failed.');
}

// 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);
}

if ($result === FTP_FINISHED) {
    echo "Upload completed successfully.\n";
}

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

In questo esempio ci colleghiamo al server FTP, accediamo con le credenziali e avviamo il caricamento con ftp_nb_put(). La prima chiamata restituisce FTP_MOREDATA, quindi entriamo in un ciclo e chiamiamo ripetutamente ftp_nb_continue() per inviare il blocco successivo — il commento // Do something else indica il punto in cui si potrebbe aggiornare una barra di avanzamento o gestire altri lavori. Quando il ciclo termina, verifichiamo FTP_FINISHED per confermare il successo, poi chiudiamo la connessione con ftp_close().

Nota: Chiama sempre ftp_nb_continue() finché il risultato non è diverso da FTP_MOREDATA. Se ti fermi prima, il caricamento rimarrà incompleto sul server.

Gestione degli errori in ftp_nb_put()

È importante gestire correttamente gli errori quando si utilizza la funzione ftp_nb_put(). Se la funzione restituisce FTP_FAILED, significa che il caricamento non è riuscito. Ecco un esempio di gestione degli errori:

Gestione degli errori in ftp_nb_put()

<?php

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

if ($result === FTP_FAILED) {
    echo "Failed to upload file to remote server.\n";
}

while ($result === FTP_MOREDATA) {
    // Do something else while waiting for the FTP operation to complete
    $result = ftp_nb_continue($conn);
}

if ($result === FTP_FINISHED) {
    echo "Upload completed.\n";
}

ftp_close($conn);

Gestendo correttamente gli errori e verificando il valore restituito dalla funzione, puoi garantire il successo delle operazioni FTP con la funzione ftp_nb_put().

Funzioni correlate

• ftp_put() — carica un file in modalità bloccante (più semplice, ma mette in pausa lo script).
• ftp_nb_continue() — continua un trasferimento non bloccante avviato da ftp_nb_put().
• ftp_nb_fput() — caricamento non bloccante da un file handle già aperto invece di un percorso.
• ftp_nb_get() — la controparte per il download di ftp_nb_put().

Conclusione

La funzione ftp_nb_put() carica file su un server FTP in modalità non bloccante, consentendo allo script di continuare con altri lavori mentre il trasferimento avviene in background. La chiave è avviare il caricamento, iterare su ftp_nb_continue() finché lo stato è FTP_MOREDATA e verificare FTP_FINISHED (gestendo FTP_FAILED) prima di chiudere la connessione. Con un utilizzo corretto e una gestione appropriata degli errori, è uno strumento prezioso per trasferimenti di file reattivi nei progetti PHP.

Nota: Le funzioni ftp_nb_* sono considerate legacy nel PHP moderno. Per i nuovi progetti, valuta l'utilizzo di cURL o di una libreria HTTP asincrona come Guzzle per migliori prestazioni, sicurezza e un supporto più ampio dei protocolli.

Pratica