PHP FTP

Introduzione

FTP (File Transfer Protocol) è un protocollo di rete standard per trasferire file tra un client e un server tramite una connessione TCP. PHP include un'estensione FTP integrata (ext-ftp) che permette agli script di accedere a un server remoto e gestire i file in modo programmatico — utile per distribuire risorse, sincronizzare backup o recuperare feed di dati dal server di un partner.

Questo capitolo copre l'intero flusso di lavoro: connessione, autenticazione, passaggio alla modalità passiva, caricamento e download, elenco e gestione dei file remoti, e infine chiusura corretta della connessione. Illustra anche le avvertenze di sicurezza da conoscere prima di utilizzare FTP semplice in produzione.

Nota sulla sicurezza. Il protocollo FTP semplice invia nome utente, password e contenuti dei file in chiaro. Per qualsiasi dato sensibile, utilizza ftp_ssl_connect() (FTP su TLS) oppure preferisci SFTP (SSH File Transfer Protocol), che l'estensione FTP non supporta — usa l'estensione PHP SSH2 o una libreria come phpseclib per SFTP.

Il flusso di lavoro FTP tipico

Ogni script FTP segue la stessa struttura, indipendentemente dall'operazione eseguita:

1. Connetti al server — ftp_connect() (oppure ftp_ssl_connect() per FTPS).
2. Autenticati — ftp_login().
3. Configura — di solito ftp_pasv($conn, true) per abilitare la modalità passiva.
4. Trasferisci / gestisci i file — ftp_put(), ftp_get(), ftp_nlist(), ecc.
5. Chiudi — ftp_close().

Connessione a un Server FTP

Stabilisci una connessione con ftp_connect(). Accetta il nome host (e facoltativamente porta e timeout) e restituisce un oggetto FTP\Connection in caso di successo (una resource prima di PHP 8.1), oppure false in caso di errore.

<?php

$conn = ftp_connect("ftp.example.com", 21, 10); // host, port, timeout (seconds)
if ($conn === false) {
    die("Could not connect to FTP server");
}
echo "Connected.";

Tieni presente che la connessione non effettua il login — a questo punto hai un canale anonimo e non autenticato. Devi ancora chiamare ftp_login() prima che il server ti permetta di fare qualcosa di utile.

Utilizzo di FTPS (FTP su TLS)

Per cifrare i canali di controllo e dati, sostituisci ftp_connect() con ftp_ssl_connect(). Il resto dell'API è identico:

<?php

$conn = ftp_ssl_connect("ftp.example.com");
if ($conn === false) {
    die("Could not open a secure FTP connection");
}

Login e Modalità Passiva

Dopo la connessione, autenticati con ftp_login(). Per i server pubblici che consentono l'accesso anonimo, usa il nome utente anonymous con una password simile a un indirizzo email.

<?php

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

if (!ftp_login($conn, "username", "password")) {
    ftp_close($conn);
    die("Login failed");
}

// Most networks behind a firewall/NAT require passive mode.
ftp_pasv($conn, true);

echo "Logged in.";

Perché la modalità passiva è importante. In modalità attiva il server apre una connessione dati verso il tuo client, che firewall e router NAT bloccano quasi sempre. In modalità passiva è il client ad aprire la connessione dati verso il server, funzionando così anche dietro i firewall. Come regola generale, chiama ftp_pasv($conn, true) subito dopo il login. Deve essere impostata dopo ftp_login(), non prima.

Caricamento di File

Usa ftp_put() per inviare un file locale al server. La firma è ftp_put($conn, $remote_file, $local_file, $mode), dove $mode è FTP_BINARY o FTP_ASCII.

<?php

$conn = ftp_connect("ftp.example.com");
ftp_login($conn, "username", "password");
ftp_pasv($conn, true);

if (ftp_put($conn, "/public_html/report.pdf", "report.pdf", FTP_BINARY)) {
    echo "Upload successful";
} else {
    echo "Upload failed";
}

ftp_close($conn);

FTP_BINARY vs FTP_ASCII. Usa FTP_BINARY per tutto ciò che non è testo semplice — immagini, PDF, archivi, eseguibili — perché la modalità ASCII riscrive i caratteri di fine riga e corrompe i dati binari. Usa FTP_ASCII solo quando vuoi specificamente tradurre i fine riga tra piattaforme per file di testo. In caso di dubbio, scegli FTP_BINARY; è il default sicuro.

Per file di grandi dimensioni puoi caricare in modalità non bloccante con ftp_nb_put(), che consente allo script di svolgere altre operazioni tra i blocchi.

Download di File

ftp_get() recupera un file remoto nel filesystem locale. L'ordine degli argomenti è ftp_get($conn, $local_file, $remote_file, $mode) — nota che la destinazione locale viene prima, al contrario di ftp_put(). Confondere questi parametri è il bug FTP più comune.

<?php

$conn = ftp_connect("ftp.example.com");
ftp_login($conn, "username", "password");
ftp_pasv($conn, true);

// local_file first, then remote_file
if (ftp_get($conn, "backup.zip", "/backups/backup.zip", FTP_BINARY)) {
    echo "Download successful";
} else {
    echo "Download failed";
}

ftp_close($conn);

Elenco e Gestione dei File Remoti

L'estensione FTP fa molto di più che trasferire file. Le funzioni di gestione più comuni includono:

<?php

$conn = ftp_connect("ftp.example.com");
ftp_login($conn, "username", "password");
ftp_pasv($conn, true);

$files = ftp_nlist($conn, "/public_html");
foreach ($files as $file) {
    echo $file, " — ", ftp_size($conn, $file), " bytes\n";
}

ftp_close($conn);

Chiusura della Connessione

Rilascia sempre la connessione con ftp_close() quando hai finito. Racchiudere il flusso di lavoro in un blocco try/finally garantisce che il socket venga chiuso anche in caso di errore nel mezzo dell'esecuzione:

<?php

$conn = ftp_connect("ftp.example.com");
if (!$conn || !ftp_login($conn, "username", "password")) {
    die("Connection or login failed");
}

try {
    ftp_pasv($conn, true);
    ftp_put($conn, "/public_html/index.html", "index.html", FTP_BINARY);
} finally {
    ftp_close($conn);
}

Buone Pratiche e Insidie

• Preferisci FTPS o SFTP. Non inviare mai credenziali tramite FTP semplice su Internet pubblico.
• Abilita sempre la modalità passiva (ftp_pasv) a meno che tu non abbia un motivo specifico per non farlo.
• Scegli la modalità di trasferimento corretta — FTP_BINARY per i dati binari, FTP_ASCII solo per testo dove si desidera la traduzione dei fine riga.
• Attenzione all'ordine degli argomenti — ftp_put è (remote, local), ftp_get è (local, remote).
• Chiudi sempre la connessione con ftp_close().
• Controlla ogni valore restituito. Le funzioni FTP restituiscono false in caso di errore anziché lanciare eccezioni, quindi gli errori silenziosi sono facili da non notare.
• ext-ftp deve essere abilitato. Verifica con extension_loaded('ftp'); se restituisce false, abilita l'estensione nel tuo php.ini.

Argomenti Correlati

• PHP File Handling — lettura e scrittura di file locali.
• PHP File Upload — gestione dei caricamenti da form HTTP.
• PHP Filesystem — il set completo di funzioni per il filesystem.
• PHP Exceptions — gestione strutturata degli errori con try/finally.

Pratica