ftp_nb_fput()

Comprendere la funzione PHP ftp_nb_fput()

La funzione ftp_nb_fput() è una funzione PHP integrata che carica un file su un server FTP usando la modalità non bloccante. "Non bloccante" significa che la funzione restituisce il controllo allo script prima che il trasferimento sia completato, consentendo di eseguire altro codice (aggiornare una barra di avanzamento, elaborare un altro compito) mentre il caricamento è ancora in corso. Questo articolo spiega i parametri, i valori restituiti e un pattern di utilizzo completo per impiegarla nei tuoi progetti PHP.

La controparte bloccante è ftp_fput(), che attende semplicemente il completamento dell'intero caricamento del file. Usa ftp_nb_fput() solo quando hai bisogno di eseguire operazioni durante il trasferimento.

Cos'è ftp_nb_fput()?

La funzione ftp_nb_fput() carica un file su un server FTP in modalità non bloccante. Accetta quattro parametri obbligatori e uno opzionale:

1. ftp_stream: L'identificatore di connessione restituito da ftp_connect().
2. remote_file: Il percorso al file remoto sul server FTP.
3. handle: Un puntatore a file aperto al file locale.
4. mode: La modalità di trasferimento, FTP_ASCII o FTP_BINARY.
5. startpos (opzionale): La posizione nel file remoto da cui avviare il caricamento. Il valore predefinito è 0.

La funzione restituisce una delle seguenti costanti: FTP_SUCCESS (caricamento completato), FTP_MOREDATA (sono necessari altri dati da leggere) oppure FTP_FAILED (si è verificato un errore).

Sintassi di ftp_nb_fput()

La sintassi della funzione ftp_nb_fput() è la seguente:

int ftp_nb_fput ( resource $ftp_stream , string $remote_file , resource $handle , int $mode [, int $startpos = 0 ] )

La funzione accetta quattro parametri obbligatori (ftp_stream, remote_file, handle e mode) e uno opzionale (startpos). Il parametro ftp_stream è l'identificatore di connessione restituito da ftp_connect(). Il parametro remote_file è il percorso al file remoto sul server FTP. Il parametro handle è un puntatore a file aperto nel file system locale. Il parametro mode specifica la modalità di trasferimento, FTP_ASCII o FTP_BINARY. Il parametro startpos specifica la posizione nel file remoto da cui avviare il caricamento. Per impostazione predefinita, startpos è impostato a 0, il che significa che il caricamento inizierà dall'inizio del file.

Utilizzo di ftp_nb_fput()

Per usare la funzione ftp_nb_fput(), devi prima stabilire una connessione al server FTP tramite la funzione ftp_connect() e autenticarti con ftp_login(). Ecco un esempio completo:

<?php

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

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

// Enable passive mode to prevent transfer issues
ftp_pasv($conn, true);

// Open a file for reading
$handle = fopen('local_file.txt', 'r');

// Initiate an asynchronous FTP operation
$res = ftp_nb_fput($conn, 'remote_file.txt', $handle, FTP_BINARY);

// Continue the asynchronous FTP operation
while ($res == FTP_MOREDATA) {
    $res = ftp_nb_continue($conn);
}

// Check for errors
if ($res != FTP_FAILED && $res != FTP_SUCCESS) {
    echo "FTP upload failed.\n";
}

// Close the file
fclose($handle);

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

In questo esempio, stabiliamo una connessione al server FTP, effettuiamo il login con le nostre credenziali e abilitiamo la modalità passiva con ftp_pasv() per prevenire i problemi di trasferimento comuni dietro i firewall. Apriamo il file locale in lettura, quindi chiamiamo ftp_nb_fput() per avviare il caricamento. Il dettaglio fondamentale è il ciclo while: finché ftp_nb_fput() (o le successive chiamate) restituisce FTP_MOREDATA, manteniamo attivo il trasferimento con ftp_nb_continue(). In un'applicazione reale, ogni iterazione di quel ciclo è il momento in cui potresti svolgere altro lavoro, poiché il trasferimento è non bloccante.

Gestione degli errori in ftp_nb_fput()

È importante gestire correttamente gli errori quando si utilizza la funzione ftp_nb_fput(). La funzione restituisce costanti specifiche anziché un valore booleano, quindi devi verificare FTP_FAILED per rilevare gli errori. Ecco un esempio di come gestire gli errori:

<?php

// Assume $conn is already established and logged in
$handle = fopen('local_file.txt', 'r');
$res = ftp_nb_fput($conn, 'remote_file.txt', $handle, FTP_BINARY);

if ($res == FTP_FAILED) {
    echo "Failed to initiate upload.\n";
}

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

if ($res == FTP_FAILED) {
    echo "Failed to complete upload.\n";
}

fclose($handle);
ftp_close($conn);

Gestendo gli errori in modo appropriato e verificando le costanti restituite sia da ftp_nb_fput() che da ftp_nb_continue(), puoi garantire il successo delle tue operazioni FTP.

ftp_nb_fput() vs. funzioni correlate

PHP offre diverse funzioni per il caricamento FTP. La scelta di quella giusta dipende dal fatto che tu disponga di un handle di file aperto o solo di un percorso, e se hai bisogno di un comportamento non bloccante:

• ftp_fput() — carica da un handle di file aperto, bloccante fino al completamento.
• ftp_put() — carica da un percorso file locale, bloccante fino al completamento.
• ftp_nb_put() — caricamento non bloccante da un percorso file locale (stesso pattern con ciclo di questa funzione).
• ftp_nb_fput() — caricamento non bloccante da un handle di file aperto (questa funzione).

Tutte le varianti non bloccanti condividono lo stesso ciclo FTP_MOREDATA / ftp_nb_continue().

Conclusione

La funzione ftp_nb_fput() carica un file su un server FTP in modalità non bloccante, permettendo allo script di continuare ad eseguire altre operazioni mentre il trasferimento è in corso. Il pattern essenziale è: avvia il caricamento, poi esegui il ciclo con ftp_nb_continue() finché il valore restituito è FTP_MOREDATA, e verifica FTP_FAILED a ogni passaggio. Usata correttamente, migliora la reattività del codice di trasferimento file nei tuoi progetti PHP.

Esercitazione