ftp_get()

Cos'è ftp_get()?

ftp_get() è una funzione built-in di PHP che scarica un file da un server FTP e lo scrive in un file locale sulla tua macchina. È la controparte in lettura di ftp_put(), che carica i file. Usala ogni volta che devi prelevare un file (un backup, un log, un report) da un server remoto tramite FTP.

Questa pagina spiega cosa fa ftp_get(), i suoi parametri e il valore restituito, un flusso di lavoro completo (connessione → accesso → download → chiusura), come gestire i fallimenti e le insidie comuni che possono capitare (modalità di trasferimento, modalità passiva e ripresa dei download parziali).

Parametri

ftp_get() accetta cinque parametri — tre obbligatori e due opzionali:

Valore restituito

La funzione restituisce un boolean: true in caso di successo, false in caso di fallimento. Verificalo sempre — un download fallito non genera un'eccezione per impostazione predefinita.

FTP_BINARY vs FTP_ASCII

FTP_BINARY trasferisce il file byte per byte ed è corretto per quasi tutto: immagini, PDF, archivi, eseguibili e anche la maggior parte dei file di testo. FTP_ASCII esegue la conversione automatica dei caratteri di fine riga tra le convenzioni del server e del client, quindi usalo solo per file di testo normale quando vuoi effettivamente quella conversione. L'uso di FTP_ASCII su un file binario lo corromperà, quindi in caso di dubbio scegli FTP_BINARY.

Sintassi di ftp_get()

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

Nota: In PHP 8.1+, il tipo resource per le connessioni FTP è stato sostituito da un oggetto Ftp\Connection, e il parametro mode è diventato opzionale (con valore predefinito FTP_BINARY). La firma legacy con resource mostrata sopra è mantenuta per compatibilità con le versioni precedenti — il tuo codice non ha bisogno di cambiare.

Utilizzo di ftp_get()

Per usare ftp_get(), devi prima stabilire una connessione con ftp_connect() e autenticarti con ftp_login(). Ecco il flusso completo:

Scaricare un file con ftp_get()

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

// 2. Log in with your FTP credentials
if (!ftp_login($conn, 'username', 'password')) {
    ftp_close($conn);
    die("Login failed.\n");
}

// 3. Switch to passive mode (required behind most firewalls/NAT)
ftp_pasv($conn, true);

// 4. Download the remote file into a local path
if (ftp_get($conn, '/local/directory/local_file.txt', 'remote_file.txt', FTP_BINARY)) {
    echo "File retrieved successfully.\n";
} else {
    echo "Failed to retrieve the file.\n";
}

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

I passaggi sono sempre gli stessi: connetti, accedi, abilita facoltativamente la modalità passiva, scarica, poi chiudi. La modalità passiva (ftp_pasv()) è abilitata qui perché la maggior parte dei client si trova dietro un firewall o NAT e i trasferimenti in modalità attiva altrimenti si bloccherebbero o fallirebbero. Nota che devi chiamare ftp_pasv() dopo aver effettuato l'accesso.

Gestione degli errori in ftp_get()

ftp_get() restituisce false in caso di fallimento invece di generare un'eccezione, quindi controlla il valore restituito in modo esplicito. Le cause comuni sono un file remoto mancante, permessi insufficienti o un percorso locale non scrivibile. PHP emette anche un avviso, che puoi catturare per il logging:

Catturare il motivo per cui un download è fallito

<?php
// $conn is an open, logged-in FTP connection
$ok = @ftp_get($conn, '/local/directory/local_file.txt', 'remote_file.txt', FTP_BINARY);

if ($ok === false) {
    $error = error_get_last();
    echo "Failed to retrieve the file: " . ($error['message'] ?? 'unknown error') . "\n";
} else {
    echo "File retrieved successfully.\n";
}

Il @ sopprime l'avviso PHP grezzo così puoi formattare il tuo messaggio, mentre error_get_last() ti fornisce comunque il dettaglio sottostante per un log.

Riprendere un download interrotto

Il parametro opzionale resumepos ti consente di continuare un download che è stato interrotto, invece di ricominciare dall'inizio. Passa la dimensione attuale del file locale parzialmente scaricato come offset in byte:

Riprendere con resumepos

<?php
// $conn is an open, logged-in FTP connection
$local = '/local/directory/big_archive.zip';

// Continue from however many bytes we already have locally
$offset = file_exists($local) ? filesize($local) : 0;

if (ftp_get($conn, $local, 'big_archive.zip', FTP_BINARY, $offset)) {
    echo "Download complete.\n";
} else {
    echo "Resume failed.\n";
}

La ripresa funziona in modo affidabile solo con FTP_BINARY e su server che supportano il comando REST. Per trasferimenti di grandi dimensioni puoi anche esaminare la variante non bloccante ftp_nb_get(), che scarica in background così il tuo script può fare altro lavoro.

Funzioni correlate

• ftp_put() — carica un file locale sul server (l'inverso di ftp_get()).
• ftp_fget() — scarica in un handle di file già aperto invece di un percorso.
• ftp_size() — ottieni la dimensione di un file remoto prima di scaricarlo.
• ftp_connect() e ftp_login() — apri e autentica la connessione.
• ftp_close() — chiudi la connessione quando hai finito.

Riepilogo

ftp_get() scarica un file remoto tramite FTP e lo salva localmente, restituendo true in caso di successo e false in caso di fallimento. Connettiti e accedi prima, preferisci FTP_BINARY a meno che tu non abbia specificamente bisogno della conversione dei caratteri di fine riga ASCII, abilita la modalità passiva quando sei dietro un firewall e controlla sempre il valore restituito affinché i fallimenti non passino silenziosamente.

Pratica