ftp_connect()

A Função PHP ftp_connect()

ftp_connect() abre uma conexão de controle com um servidor FTP e retorna um handle de conexão que todas as outras funções FTP (ftp_login(), ftp_get(), ftp_put(), …) precisam como primeiro argumento. Pense nisso como discar para o servidor: a chamada apenas abre o canal — ela não autentica você. Ainda é necessário fazer login com ftp_login() antes de poder transferir arquivos.

Esta página aborda a sintaxe, os três parâmetros, um fluxo de trabalho completo de conectar-autenticar-fechar, como lidar com falhas e como ftp_connect() se relaciona com sua versão segura, ftp_ssl_connect().

Sintaxe

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

Valor de retorno. Em caso de sucesso, você obtém um objeto de conexão — uma instância de FTP\Connection a partir do PHP 8.1, ou um resource em versões anteriores. Em caso de falha, retorna false, portanto o resultado deve sempre ser verificado antes do uso.

Nota: ftp_connect() estabelece uma conexão não criptografada — credenciais e dados trafegam em texto simples. Para qualquer uso sobre a internet pública, prefira ftp_ssl_connect() (FTPS).

Um fluxo completo de conectar → autenticar → fechar

Uma sessão típica abre a conexão, autentica, executa o trabalho e então fecha o 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);

Cada etapa corresponde a uma função dedicada: ftp_login() autentica, ftp_pasv() alterna o modo passivo, ftp_put() e ftp_get() transferem arquivos, e ftp_close() encerra a conexão.

Lidando com uma conexão com falha

Como ftp_connect() retorna false em caso de falha, trate um handle ausente como uma parada obrigatória — chamar funções FTP posteriores com false aciona um TypeError. Verifique tanto a conexão quanto o 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);

Use uma comparação estrita com === false em vez de !$conn. Os dois se comportam da mesma forma para ftp_connect(), mas === false torna sua intenção explícita e evita surpresas quando uma função pode retornar legitimamente um valor vazio mas verdadeiro.

Problemas comuns

• A extensão FTP pode estar desabilitada. As funções ftp_* exigem PHP compilado com --enable-ftp (ou o pacote php-ftp). Proteja com if (!function_exists('ftp_connect')) { ... } se a portabilidade for importante.
• Modo passivo. Se ftp_connect() e ftp_login() tiverem êxito, mas listagens ou transferências travarem, o servidor provavelmente está atrás de um firewall — alterne para o modo passivo com ftp_pasv($conn, true) após o login.
• Conectar não é autenticar. Um handle retornado significa apenas que o canal TCP está aberto. Uma senha errada falha posteriormente, em ftp_login().
• Sem prefixo ftp://. Passe apenas o nome do host; o esquema está implícito na função.

Para uma visão geral de todo o conjunto de ferramentas FTP, consulte a referência de funções FTP do PHP.

Prática