ftp_fput()

Cos'è ftp_fput()?

La funzione ftp_fput() è una funzione built-in di PHP che carica un file sul server FTP. La funzione accetta cinque parametri:

1. ftp_stream: L'identificatore di connessione restituito dalla funzione ftp_connect().
2. remote_file: Il nome del file remoto su cui caricare il file.
3. local_file: Una risorsa file handle aperta con fopen() che punta al file locale da caricare.
4. mode (opzionale): La modalità di trasferimento (FTP_ASCII o FTP_BINARY). Il valore predefinito è FTP_ASCII.
5. startpos (opzionale): La posizione iniziale nel file remoto per il caricamento. Il valore predefinito è 0.

La funzione restituisce un valore boolean. Se il caricamento del file ha successo, restituisce true. Altrimenti, restituisce false.

Quando usare ftp_fput() invece di ftp_put()

ftp_put() accetta come parametro un percorso locale del file come string e apre il file automaticamente. ftp_fput() accetta invece un handle di file già aperto. Usa ftp_fput() quando:

• I dati da caricare non si trovano in un file ordinario su disco — ad esempio uno stream temporaneo creato con php://temp, oppure l'output di un'altra risorsa già aperta.
• Hai bisogno di un controllo preciso sulla posizione di lettura (combinato con il parametro startpos, puoi riprendere un caricamento interrotto).
• Hai già aperto l'handle per un altro motivo e vuoi evitare di aprire lo stesso file due volte.

Se vuoi semplicemente caricare un file esistente per nome, ftp_put() è più semplice. Per caricamenti non bloccanti (asincroni), vedi ftp_nb_fput().

Sintassi di ftp_fput()

La sintassi della funzione ftp_fput() è la seguente:

Sintassi di ftp_fput()

bool ftp_fput ( resource $ftp_stream , string $remote_file , resource $local_file [, int $mode = FTP_ASCII [, int $startpos = 0 ]] )

Utilizzo di ftp_fput()

Per usare la funzione ftp_fput(), devi prima stabilire una connessione al server FTP tramite la funzione ftp_connect(). Ecco un esempio:

Utilizzo di ftp_fput() in PHP

<?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.");
}

// Open the local file
$local_file = fopen('/local/directory/local_file.txt', 'r');
if (!$local_file) {
    die("Could not open local file.");
}

// Upload the file to the remote FTP server
if (ftp_fput($conn, 'remote_file.txt', $local_file, FTP_ASCII)) {
    echo "File uploaded successfully.\n";
} else {
    echo "Failed to upload the file.\n";
}

// Close the file handle and FTP connection
fclose($local_file);
ftp_close($conn);

In questo esempio, stabiliamo una connessione al server FTP usando la funzione ftp_connect() e verifichiamo che abbia avuto successo. Poi effettuiamo il login con le nostre credenziali FTP tramite ftp_login() e controlliamo eventuali errori. Successivamente, apriamo il file locale con fopen() per ottenere il file handle necessario. Infine, carichiamo il file sul server FTP remoto usando ftp_fput() e chiudiamo sia il file handle che la connessione FTP con ftp_close().

Scegliere la modalità di trasferimento: FTP_ASCII vs FTP_BINARY

Il parametro mode controlla come vengono trasferiti i byte ed è più importante di quanto sembri:

• FTP_BINARY trasferisce il file byte per byte, senza modifiche. Usalo per immagini, archivi, eseguibili, PDF — qualsiasi cosa che non sia testo semplice. È il valore predefinito sicuro per quasi tutto.
• FTP_ASCII traduce le terminazioni di riga tra la piattaforma locale e quella remota (ad es. \n ↔ \r\n). È appropriato solo per file di testo semplice; usarlo su dati binari corromperà il file in modo silenzioso.

Quando apri l'handle locale, abbina la modalità di fopen() al trasferimento: usa 'rb' (read binary) insieme a FTP_BINARY in modo che PHP non alteri i byte durante la lettura:

<?php

$local_file = fopen('/local/directory/photo.jpg', 'rb');
ftp_fput($conn, 'photo.jpg', $local_file, FTP_BINARY);
fclose($local_file);

Gestione degli errori in ftp_fput()

È importante gestire correttamente gli errori quando si usa la funzione ftp_fput(). Se la funzione restituisce false, significa che il file non è stato caricato per qualche motivo. Ecco un esempio di come gestire gli errori:

Gestione degli errori in ftp_fput()

<?php

// Assuming $conn is already established via ftp_connect() and ftp_login()
$local_file = fopen('/local/directory/local_file.txt', 'rb');

if ($local_file === false) {
    echo "Could not open the local file.\n";
} elseif (ftp_fput($conn, 'remote_file.txt', $local_file, FTP_BINARY)) {
    echo "File uploaded successfully.\n";
    fclose($local_file);
} else {
    echo "Failed to upload the file.\n";
    fclose($local_file);
}

Nota l'ordine dei controlli: prima verifichiamo che fopen() abbia restituito un handle valido, poi chiamiamo ftp_fput(). Chiamare fclose() su un handle false (cosa che accade se l'esempio originale salta il controllo sull'apertura) genera un avviso, quindi chiudiamo l'handle solo nei rami in cui è stato effettivamente aperto. Questo impedisce che il messaggio di "successo" venga mai stampato quando il caricamento non è avvenuto.

Errori comuni

• Passare un percorso invece di un handle. ftp_fput() si aspetta la risorsa restituita da fopen(), non una string con il nome del file. Se hai un percorso, usa ftp_put().
• Modalità di trasferimento errata. Caricare un file binario con FTP_ASCII lo corrompe. In caso di dubbio, usa FTP_BINARY.
• Non chiudere l'handle. Chiama sempre fclose() una volta completato il trasferimento per liberare la risorsa.
• Modalità passiva. Dietro un firewall, molti server richiedono la modalità passiva. Chiama ftp_pasv($conn, true) dopo il login se i caricamenti si bloccano.

Conclusione

La funzione ftp_fput() carica un file su un server FTP da un file handle aperto, rendendola la scelta giusta quando i tuoi dati si trovano già in uno stream anziché a un percorso fisso su disco. Abbinala alla modalità di trasferimento corretta, controlla i valori restituiti sia da fopen() che da ftp_fput(), chiudi i tuoi handle, e funzionerà in modo affidabile nei tuoi progetti PHP.

Pratica