ftp_ssl_connect()

Comprendere la funzione PHP ftp_ssl_connect()

La funzione ftp_ssl_connect() apre una connessione FTPS esplicita (FTP su SSL/TLS) verso un server FTP. È la controparte sicura di ftp_connect(): entrambe restituiscono un handle di connessione da passare alle altre funzioni ftp_*, ma ftp_ssl_connect() aggiorna il canale di controllo a una sessione TLS cifrata, in modo che le credenziali di accesso e i comandi non vengano inviati in chiaro.

Questa pagina illustra cosa fa la funzione, i suoi parametri e il valore restituito, un esempio completo funzionante e le insidie più comuni (FTPS vs. SFTP, verifica dei certificati e modalità passiva).

Cos'è ftp_ssl_connect()?

La funzione ftp_ssl_connect() stabilisce una connessione cifrata SSL/TLS verso un server FTP. Richiede che PHP sia compilato con l'estensione ftp e l'estensione openssl. Accetta tre parametri:

host: Il nome del server FTP a cui connettersi.
port: Il numero di porta a cui connettersi. Questo parametro è opzionale e ha come valore predefinito la porta 21.
timeout: Il timeout per il tentativo di connessione in secondi. Questo parametro è opzionale e ha come valore predefinito 90 secondi.

Nota: Per impostazione predefinita, PHP verifica i certificati SSL utilizzando il bundle CA del sistema. Per gli ambienti di produzione, assicurati che i certificati CA siano aggiornati per evitare errori di connessione.

La funzione restituisce un handle di connessione FTP in caso di successo (un oggetto FTP\Connection in PHP 8.1+, o una risorsa nelle versioni precedenti) e false in caso di errore.

FTPS vs. SFTP — scegli il protocollo giusto

Questi due protocolli vengono spesso confusi perché entrambi trasferiscono file in modo sicuro, ma sono protocolli del tutto distinti:

FTPS (quello utilizzato da questa funzione) è il protocollo FTP incapsulato in TLS. Usa ftp_ssl_connect() e il resto della famiglia ftp_*.
SFTP è un sottosistema di SSH e non ha nulla a che fare con FTP. PHP non può raggiungerlo tramite le funzioni ftp_* — occorre usare l'estensione ssh2_* o una libreria come phpseclib.

Se il tuo server offre solo SSH/SFTP, ftp_ssl_connect() non riuscirà a connettersi.

Sintassi di ftp_ssl_connect()

La sintassi della funzione ftp_ssl_connect() è la seguente:

Sintassi di ftp_ssl_connect()

resource ftp_ssl_connect ( string $host [, int $port = 21 [, int $timeout = 90 ]] )

La funzione ftp_ssl_connect() accetta tre parametri, tutti opzionali ad eccezione del parametro host. Il parametro port specifica il numero di porta a cui connettersi, mentre il parametro timeout specifica il timeout per il tentativo di connessione in secondi.

Utilizzo di ftp_ssl_connect()

Per utilizzare la funzione ftp_ssl_connect(), è sufficiente chiamare la funzione e passare i parametri richiesti. Ecco un esempio:

Utilizzo di ftp_ssl_connect()

<?php

// Set up a secure SSL-encrypted FTP connection
$conn = ftp_ssl_connect('ftp.example.com', 21, 60);

// Login with your FTP credentials
ftp_login($conn, 'username', 'password');

// Perform FTP operations

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

In questo esempio, stabiliamo una connessione cifrata SSL/TLS verso il server FTP tramite la funzione ftp_ssl_connect(). Quindi accediamo con le nostre credenziali FTP utilizzando la funzione ftp_login(). Dopo l'accesso, possiamo eseguire le operazioni FTP necessarie. Infine, chiudiamo la connessione FTP con la funzione ftp_close().

Un upload completo e pronto per la produzione

L'esempio minimo sopra riportato tralascia i controlli realmente necessari nel codice in produzione. La versione seguente verifica che la connessione e il login abbiano avuto esito positivo, attiva la modalità passiva (richiesta dalla maggior parte dei firewall e NAT) e carica un file:

Upload FTPS completo

<?php

$host = 'ftp.example.com';
$user = 'username';
$pass = 'password';

// 1. Open the secure connection (false on failure)
$conn = ftp_ssl_connect($host, 21, 30);
if ($conn === false) {
    exit("Could not connect to {$host}\n");
}

// 2. Authenticate
if (!ftp_login($conn, $user, $pass)) {
    ftp_close($conn);
    exit("Login failed for {$user}\n");
}

// 3. Passive mode — almost always required for FTPS behind a firewall
ftp_pasv($conn, true);

// 4. Upload a local file in binary mode
if (ftp_put($conn, 'remote/report.csv', 'local/report.csv', FTP_BINARY)) {
    echo "Upload succeeded\n";
} else {
    echo "Upload failed\n";
}

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

Le buone abitudini mostrate qui — verificare il valore restituito da ogni chiamata e abilitare la modalità passiva con ftp_pasv() — sono ciò che rende FTPS affidabile in pratica. Senza la modalità passiva, i trasferimenti di dati si bloccano spesso dietro i firewall, perché il server tenta di aprire una connessione di ritorno che il client non riesce ad accettare.

Gestione degli errori in ftp_ssl_connect()

È importante gestire correttamente gli errori quando si utilizza la funzione ftp_ssl_connect(). Se la funzione restituisce false, significa che l'operazione non è riuscita. Ecco un esempio di come gestire gli errori:

Gestione degli errori in ftp_ssl_connect()

<?php

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

if ($conn === false) {
    echo "Failed to establish a secure SSL-encrypted connection to the FTP server.\n";
} else {
    // Perform FTP operations

    // Close the FTP connection
    ftp_close($conn);
}

Gestendo gli errori in modo appropriato e verificando il valore restituito dalla funzione, puoi garantire il successo delle operazioni FTP che utilizzano ftp_ssl_connect().

Insidie comuni

Un handle restituito non significa che hai effettuato l'accesso. ftp_ssl_connect() apre soltanto il canale cifrato; è ancora necessario un ftp_login() andato a buon fine prima che qualsiasi operazione funzioni.
Dimenticare la modalità passiva. La maggior parte dei trasferimenti dati si blocca dietro firewall o NAT se non si chiama ftp_pasv($conn, true) dopo il login.
Confondere FTPS con SFTP. Come indicato sopra, questa funzione non può comunicare con un server SSH/SFTP.
Verifica che la funzione esista. È disponibile solo quando PHP è compilato con entrambe le estensioni ftp e openssl. Usa function_exists('ftp_ssl_connect') come guardia se non puoi garantire la build.
FTPS implicito (porta 990) non è supportato. ftp_ssl_connect() esegue solo FTPS esplicito. Per FTPS implicito, utilizza un wrapper di stream o una libreria dedicata.

Funzioni correlate

ftp_connect() — apre una connessione FTP normale (non cifrata).
ftp_login() — autentica dopo la connessione.
ftp_pasv() — attiva o disattiva la modalità di trasferimento passiva.
ftp_get() / ftp_put() — scarica e carica file.
ftp_close() — chiude la connessione.
Panoramica FTP di PHP — l'intera famiglia di funzioni FTP.

Conclusione

La funzione ftp_ssl_connect() è il punto d'ingresso sicuro nel toolkit FTP di PHP: apre una connessione FTPS esplicita in modo che le credenziali e i comandi viaggino su TLS anziché in chiaro. Abbinala a un ftp_login() verificato, abilita la modalità passiva e controlla ogni valore restituito: otterrai un flusso di trasferimento file affidabile e sicuro. Quando il server remoto utilizza SSH/SFTP invece di FTPS, usa l'estensione ssh2_*.

Pratica

Qual è la funzione di ftp_ssl_connect() in PHP?

Apre una connessione FTP SSL-FTP.Chiude una connessione FTP SSL-FTPStabilisce una connessione FTP normaleConsente trasferimenti di file sicuri.