ftp_login()

La funzione PHP ftp_login() autentica un utente su un server FTP. È il secondo passo di quasi ogni sessione FTP: prima si apre una connessione con ftp_connect(), poi si chiama ftp_login() per identificarsi prima di poter elencare, scaricare o caricare file. Questa pagina spiega i parametri, il valore restituito, come gestire un login fallito e le insidie più comuni (modalità passiva, connessioni sicure e sicurezza delle credenziali).

Cos'è ftp_login()?

ftp_login() è una funzione built-in di PHP che accede a un server FTP con nome utente e password. La connessione deve essere già aperta — ftp_login() non si connette da sola; autentica su un handle di connessione esistente.

Accetta tre parametri:

1. ftp — l'identificatore di connessione restituito da ftp_connect() (o ftp_ssl_connect()).
2. username — il nome utente con cui accedere. Usare anonymous per i server FTP anonimi.
3. password — la password con cui accedere. Per i login anonimi, è convenzionale usare un indirizzo email.

La funzione restituisce un boolean: true in caso di login riuscito, false in caso di fallimento (credenziali errate, un account non autorizzato ad accedere, ecc.).

Sintassi di ftp_login()

ftp_login(FTP\Connection $ftp, string $username, string $password): bool

Nota: Prima di PHP 8.1, il primo parametro era una resource restituita da ftp_connect(). Da PHP 8.1 in poi è un oggetto FTP\Connection. Il codice chiamante non cambia — cambia solo il tipo sottostante.

Utilizzo di base

Una sessione completa e corretta abbina sempre il login a una connessione e a una chiusura. Si noti che il valore restituito da ftp_connect() viene verificato prima ancora di tentare ftp_login(), perché effettuare il login contro false genererebbe un TypeError.

<?php

// 1. Open a connection (returns false on failure)
$conn = ftp_connect('ftp.example.com');

if ($conn === false) {
    exit("Could not connect to the FTP server.\n");
}

// 2. Authenticate
if (ftp_login($conn, 'username', 'password')) {
    echo "Logged in successfully.\n";
    // ... work with files here ...
} else {
    echo "Login failed: check the username and password.\n";
}

// 3. Always close the connection when finished
ftp_close($conn);

Le tre chiamate — connect, login, close — delimitano ogni operazione FTP. Vedere ftp_close() per capire perché è importante rilasciare l'handle.

Gestione degli errori in ftp_login()

ftp_login() restituisce false per un login errato, ma emette anche un avviso PHP. In produzione di solito si vuole sopprimere quell'avviso e decidere autonomamente cosa fare. Usare l'operatore @ per silenziare l'avviso e ramificare sul valore restituito:

<?php

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

if ($conn === false) {
    echo "Login failed.\n";
} elseif (@ftp_login($conn, 'username', 'wrong-password') === false) {
    echo "Login failed.\n";
} else {
    echo "Login successful.\n";
}

Per un host irraggiungibile o credenziali errate, questo stampa Login failed. invece di crashare o mostrare un avviso grezzo nella pagina.

Modalità passiva e login sicuri

Due problemi si presentano frequentemente dopo un login riuscito:

• Modalità passiva. Molti server (e la maggior parte delle configurazioni NAT/firewall) richiedono la modalità passiva per i trasferimenti di dati come gli elenchi di directory e i download. Attivarla con ftp_pasv() — ma solo dopo che ftp_login() ha avuto successo, mai prima.
• Cifratura. L'FTP normale invia nome utente e password in chiaro. Preferire FTP su SSL/TLS aprendo la connessione con ftp_ssl_connect(); ftp_login() funziona quindi esattamente allo stesso modo.

<?php

$conn = ftp_ssl_connect('ftp.example.com'); // encrypted control channel

if ($conn && ftp_login($conn, 'username', 'password')) {
    ftp_pasv($conn, true);                   // enable passive mode after login
    // ... transfer files ...
    ftp_close($conn);
}

Insidie comuni

• Non inserire mai le credenziali nel codice sorgente che si commette. Leggerle da variabili d'ambiente o da un file di configurazione tenuto fuori dal controllo di versione.
• ftp_login() non si connette. Se si passa una stringa con il nome host invece di un handle di connessione, si ottiene un TypeError. Chiamare sempre prima ftp_connect().
• Un ritorno true significa solo che l'autenticazione è riuscita. Non dice nulla sui permessi — un successivo upload può comunque fallire se l'account non ha accesso in scrittura.

Conclusione

ftp_login() autentica una connessione FTP aperta con nome utente e password, restituendo true o false. Connettersi sempre prima, verificare il valore restituito, abilitare la modalità passiva dopo il login quando necessario e preferire una connessione cifrata in produzione. Per il set completo di funzioni correlate, vedere il riferimento PHP FTP.

Esercitazione