ftp_connect()

La funzione PHP ftp_connect()

ftp_connect() apre una connessione di controllo verso un server FTP e restituisce un handle di connessione necessario come primo argomento a tutte le altre funzioni FTP (ftp_login(), ftp_get(), ftp_put(), …). Pensala come una telefonata al server: la chiamata apre solo il canale — non ti autentica. Devi ancora effettuare il login con ftp_login() prima di poter trasferire file.

Questa pagina tratta la sintassi, i tre parametri, un flusso di lavoro completo connetti-login-chiudi, come gestire i fallimenti e come ftp_connect() si relaziona alla sua controparte sicura, ftp_ssl_connect().

Sintassi

ftp_connect(string $hostname, int $port = 21, int $timeout = 90): FTP\Connection|false

Valore restituito. In caso di successo si ottiene un oggetto connessione — un'istanza di FTP\Connection a partire da PHP 8.1, oppure una resource nelle versioni precedenti. In caso di errore restituisce false, quindi il risultato deve sempre essere verificato prima dell'uso.

Nota: ftp_connect() stabilisce una connessione non cifrata — le credenziali e i dati viaggiano in chiaro. Per qualsiasi comunicazione su internet pubblico, preferire ftp_ssl_connect() (FTPS).

Un flusso di lavoro completo connetti → login → chiudi

Una sessione tipica apre la connessione, si autentica, esegue il proprio lavoro e poi chiude l'handle:

<?php

// 1. Open the control connection (does not log you in)
$conn = ftp_connect('ftp.example.com', 21, 30);

// 2. Authenticate
ftp_login($conn, 'username', 'password');

// 3. Many servers behind NAT/firewalls need passive mode
ftp_pasv($conn, true);

// 4. Do some work — e.g. upload a file
ftp_put($conn, 'backup.sql', 'local-backup.sql', FTP_BINARY);

// 5. Always release the connection
ftp_close($conn);

Ogni passo corrisponde a una funzione dedicata: ftp_login() autentica, ftp_pasv() attiva la modalità passiva, ftp_put() e ftp_get() trasferiscono file, e ftp_close() termina la connessione.

Gestione di una connessione fallita

Poiché ftp_connect() restituisce false in caso di errore, considera un handle mancante come un blocco definitivo — chiamare le successive funzioni FTP con false genera un TypeError. Verifica sia la connessione che il login:

<?php

$conn = ftp_connect('ftp.example.com', 21, 30);
if ($conn === false) {
    // Wrong host, blocked port 21, or DNS/network failure
    exit("Could not reach the FTP server.\n");
}

if (!ftp_login($conn, 'username', 'password')) {
    ftp_close($conn);
    exit("Login failed — check the username and password.\n");
}

echo "Connected and authenticated.\n";

// ... transfer files ...

ftp_close($conn);

Usa il confronto stretto === false invece di !$conn. I due si comportano allo stesso modo per ftp_connect(), ma === false rende esplicita l'intenzione ed evita sorprese quando una funzione può legittimamente restituire un valore vuoto ma truthy.

Errori comuni

• L'estensione FTP potrebbe essere disabilitata. Le funzioni ftp_* richiedono PHP compilato con --enable-ftp (o il pacchetto php-ftp). Verifica con if (!function_exists('ftp_connect')) { ... } se la portabilità è importante.
• Modalità passiva. Se ftp_connect() e ftp_login() hanno successo ma le liste o i trasferimenti si bloccano, il server è probabilmente dietro un firewall — passa alla modalità passiva con ftp_pasv($conn, true) dopo il login.
• Connettersi non significa autenticarsi. Un handle restituito significa solo che il canale TCP è aperto. Una password errata fallisce in seguito, a livello di ftp_login().
• Nessun prefisso ftp://. Passa un nome host semplice; lo schema è implicito nella funzione.

Per una panoramica dell'intero toolkit FTP, consulta il riferimento delle funzioni PHP FTP.

Practice