ftp_login()

A função PHP ftp_login() autentica um utilizador num servidor FTP. É o segundo passo de praticamente todas as sessões FTP: primeiro abre-se uma ligação com ftp_connect() e depois chama-se ftp_login() para se identificar antes de poder listar, descarregar ou enviar ficheiros. Esta página explica os parâmetros, o valor de retorno, como lidar com um login falhado e as armadilhas mais comuns (modo passivo, ligações seguras e segurança das credenciais).

O que é ftp_login()?

ftp_login() é uma função nativa do PHP que faz login num servidor FTP com um nome de utilizador e uma palavra-passe. A ligação já deve estar aberta — ftp_login() não se liga por si só; autentica sobre um identificador de ligação existente.

Recebe três parâmetros:

1. ftp — o identificador de ligação devolvido por ftp_connect() (ou ftp_ssl_connect()).
2. username — o nome de utilizador para o login. Use anonymous para servidores FTP anónimos.
3. password — a palavra-passe para o login. Para logins anónimos, um endereço de e-mail é convencional.

A função devolve um boolean: true em caso de login bem-sucedido, false em caso de falha (credenciais incorretas, uma conta que não tem permissão para fazer login, etc.).

Sintaxe de ftp_login()

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

Nota: Antes do PHP 8.1, o primeiro parâmetro era um resource devolvido por ftp_connect(). A partir do PHP 8.1, é um objeto FTP\Connection. O código de chamada não muda — apenas o tipo subjacente muda.

Uso básico

Uma sessão completa e correta associa sempre o login a uma ligação e a um encerramento. Note que o valor de retorno de ftp_connect() é verificado antes de ftp_login() ser sequer tentado, pois fazer login contra false geraria um 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);

As três chamadas — conectar, fazer login, fechar — enquadram cada tarefa FTP. Consulte ftp_close() para perceber por que liberar o identificador é importante.

Tratamento de erros em ftp_login()

ftp_login() devolve false para um login inválido, mas também emite um aviso PHP. Em produção, normalmente é preferível suprimir esse aviso e decidir o que fazer por conta própria. Use o operador @ para silenciar o aviso e ramificar com base no valor de retorno:

<?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";
}

Para um host inacessível ou credenciais incorretas, isto imprime Login failed. em vez de falhar ou vazar um aviso bruto para a página.

Modo passivo e logins seguros

Dois problemas surgem frequentemente após um login bem-sucedido:

• Modo passivo. Muitos servidores (e a maioria das configurações NAT/firewall) requerem o modo passivo para transferências de dados como listagens de diretórios e descarregamentos. Ative-o com ftp_pasv() — mas apenas depois de ftp_login() ter sucesso, nunca antes.
• Encriptação. O FTP simples envia o nome de utilizador e a palavra-passe em texto simples. Prefira FTP sobre SSL/TLS abrindo a ligação com ftp_ssl_connect(); ftp_login() funciona da mesma forma.

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

Armadilhas comuns

• Nunca codifique credenciais diretamente em código que vai para controlo de versão. Leia-as a partir de variáveis de ambiente ou de um ficheiro de configuração mantido fora do controlo de versão.
• ftp_login() não estabelece ligação. Se passar uma string de hostname em vez de um identificador de ligação, obtém um TypeError. Chame sempre ftp_connect() primeiro.
• Um retorno true significa apenas que a autenticação foi bem-sucedida. Não diz nada sobre permissões — um upload posterior pode ainda falhar se a conta não tiver acesso de escrita.

Conclusão

ftp_login() autentica uma ligação FTP aberta com um nome de utilizador e uma palavra-passe, devolvendo true ou false. Conecte-se sempre primeiro, verifique o valor de retorno, ative o modo passivo após o login quando necessário e prefira uma ligação encriptada em produção. Para o conjunto completo de funções relacionadas, consulte a referência PHP FTP.

Prática