ftp_ssl_connect()

Entendendo a Função PHP ftp_ssl_connect()

A função ftp_ssl_connect() abre uma conexão FTPS explícito (FTP sobre SSL/TLS) com um servidor FTP. É a versão segura de ftp_connect(): ambas retornam um identificador de conexão que você passa para as outras funções ftp_*, mas ftp_ssl_connect() atualiza o canal de controle para uma sessão TLS criptografada, de modo que suas credenciais de login e comandos não sejam enviados em texto simples.

Esta página aborda o que a função faz, seus parâmetros e valor de retorno, um exemplo funcional completo e as armadilhas mais comuns (FTPS vs. SFTP, verificação de certificados e modo passivo).

O que é ftp_ssl_connect()?

A função ftp_ssl_connect() estabelece uma conexão segura SSL/TLS criptografada com um servidor FTP. Ela requer que o PHP seja compilado com a extensão ftp e com a extensão openssl. Aceita três parâmetros:

1. host: O nome do servidor FTP ao qual se conectar.
2. port: O número da porta para a conexão. Este parâmetro é opcional e o padrão é a porta 21.
3. timeout: O tempo limite para a tentativa de conexão, em segundos. Este parâmetro é opcional e o padrão é 90 segundos.

Nota: Por padrão, o PHP verifica os certificados SSL usando o pacote CA do sistema. Em ambientes de produção, certifique-se de que seus certificados CA estejam atualizados para evitar falhas de conexão.

A função retorna um identificador de conexão FTP em caso de sucesso (um objeto FTP\Connection no PHP 8.1+, ou um resource em versões anteriores) e false em caso de falha.

FTPS vs. SFTP — escolha o correto

Esses dois protocolos são frequentemente confundidos porque ambos transferem arquivos com segurança, mas são protocolos completamente distintos:

• FTPS (o que esta função utiliza) é o protocolo FTP encapsulado em TLS. Use ftp_ssl_connect() e as demais funções da família ftp_*.
• SFTP é um subsistema do SSH e não tem nada a ver com FTP. O PHP não consegue alcançá-lo por meio das funções ftp_* — você deve usar a extensão ssh2_* ou uma biblioteca como phpseclib.

Se o seu servidor oferece apenas SSH/SFTP, ftp_ssl_connect() não conseguirá se conectar a ele.

Sintaxe de ftp_ssl_connect()

A sintaxe da função ftp_ssl_connect() é a seguinte:

Sintaxe de ftp_ssl_connect()

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

A função ftp_ssl_connect() aceita três parâmetros, todos opcionais exceto o parâmetro host. O parâmetro port especifica o número da porta para a conexão, e o parâmetro timeout especifica o tempo limite para a tentativa de conexão em segundos.

Uso de ftp_ssl_connect()

Para usar a função ftp_ssl_connect(), basta chamá-la e passar os parâmetros necessários. Veja um exemplo:

Uso de 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);

Neste exemplo, estabelecemos uma conexão segura SSL/TLS criptografada com o servidor FTP usando a função ftp_ssl_connect(). Em seguida, fazemos login com nossas credenciais FTP usando a função ftp_login(). Após o login, podemos realizar as operações FTP necessárias. Por fim, fechamos a conexão FTP com a função ftp_close().

Um upload completo, pronto para produção

O exemplo mínimo acima omite as verificações que você realmente precisa em código real. A versão abaixo verifica se a conexão e o login foram bem-sucedidos, ativa o modo passivo (obrigatório na maioria dos firewalls e NAT) e faz o upload de um arquivo:

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);

Os bons hábitos aqui — verificar o valor de retorno de cada chamada e ativar o modo passivo com ftp_pasv() — são o que tornam o FTPS confiável na prática. Sem o modo passivo, as transferências de dados frequentemente travam atrás de firewalls, pois o servidor tenta abrir uma conexão de retorno que o cliente não consegue aceitar.

Tratamento de erros em ftp_ssl_connect()

É importante tratar os erros adequadamente ao usar a função ftp_ssl_connect(). Se a função retornar false, significa que a operação não foi bem-sucedida. Veja um exemplo de como tratar erros:

Tratamento de erros em 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);
}

Ao tratar os erros adequadamente e verificar o valor de retorno da função, você garante o sucesso das suas operações FTP usando a função ftp_ssl_connect().

Armadilhas comuns

• Um identificador retornado não significa que você está autenticado. ftp_ssl_connect() apenas abre o canal criptografado; você ainda precisa de um ftp_login() bem-sucedido antes que qualquer operação funcione.
• Esquecer o modo passivo. A maioria das transferências de dados trava atrás de firewalls ou NAT a menos que você chame ftp_pasv($conn, true) após o login.
• Confundir FTPS com SFTP. Como mencionado acima, esta função não consegue se comunicar com um servidor SSH/SFTP.
• Verifique se a função existe. Ela só está disponível quando o PHP é compilado com as extensões ftp e openssl. Use function_exists('ftp_ssl_connect') como guarda caso não possa garantir a compilação.
• FTPS implícito (porta 990) não é suportado. ftp_ssl_connect() realiza apenas FTPS explícito. Para FTPS implícito, use um wrapper de stream ou uma biblioteca dedicada.

Funções relacionadas

• ftp_connect() — abre uma conexão FTP simples (não criptografada).
• ftp_login() — autentica após a conexão.
• ftp_pasv() — ativa ou desativa o modo de transferência passiva.
• ftp_get() / ftp_put() — faz download e upload de arquivos.
• ftp_close() — fecha a conexão.
• Visão geral do FTP em PHP — a família completa de funções FTP.

Conclusão

A função ftp_ssl_connect() é o ponto de entrada seguro para o kit de ferramentas FTP do PHP, abrindo uma conexão FTPS explícita para que credenciais e comandos trafeguem por TLS em vez de texto simples. Combine-a com um ftp_login() verificado, ative o modo passivo e verifique cada valor de retorno, e você terá um fluxo de transferência de arquivos confiável e seguro. Quando o servidor remoto utiliza SSH/SFTP em vez de FTPS, use a extensão ssh2_*.

Prática