ftp_login()

La función PHP ftp_login() autentica a un usuario contra un servidor FTP. Es el segundo paso de casi todas las sesiones FTP: primero se abre una conexión con ftp_connect() y luego se llama a ftp_login() para identificarse antes de poder listar, descargar o subir archivos. Esta página explica los parámetros, el valor de retorno, cómo gestionar un inicio de sesión fallido y los errores más comunes (modo pasivo, conexiones seguras y seguridad de credenciales).

¿Qué es ftp_login()?

ftp_login() es una función integrada de PHP que inicia sesión en un servidor FTP con un nombre de usuario y una contraseña. La conexión debe estar ya abierta — ftp_login() no conecta por sí misma; autentica sobre un identificador de conexión existente.

Acepta tres parámetros:

1. ftp — el identificador de conexión devuelto por ftp_connect() (o ftp_ssl_connect()).
2. username — el nombre de usuario con el que iniciar sesión. Utilice anonymous para servidores FTP anónimos.
3. password — la contraseña con la que iniciar sesión. Para inicios de sesión anónimos, se suele usar una dirección de correo electrónico.

La función devuelve un boolean: true si el inicio de sesión es exitoso, false en caso de error (credenciales incorrectas, una cuenta que no tiene permiso para iniciar sesión, etc.).

Sintaxis de ftp_login()

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

Nota: Antes de PHP 8.1, el primer parámetro era un resource devuelto por ftp_connect(). A partir de PHP 8.1 es un objeto FTP\Connection. El código de llamada no cambia — solo cambia el tipo subyacente.

Uso básico

Una sesión completa y correcta siempre empareja el inicio de sesión con una conexión y un cierre. Observe que el valor de retorno de ftp_connect() se comprueba antes de intentar siquiera ftp_login(), porque iniciar sesión contra false provocaría un 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);

Las tres llamadas — conectar, iniciar sesión, cerrar — enmarcan cada tarea FTP. Consulte ftp_close() para entender por qué es importante liberar el identificador.

Gestión de errores en ftp_login()

ftp_login() devuelve false si el inicio de sesión falla, pero también emite un aviso de PHP. En producción normalmente se desea suprimir ese aviso y decidir qué hacer por cuenta propia. Use el operador @ para silenciar el aviso y actúe según el 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 un host inaccesible o credenciales incorrectas, esto imprime Login failed. en lugar de fallar o mostrar un aviso sin procesar en la página.

Modo pasivo e inicios de sesión seguros

Dos problemas frecuentes tras un inicio de sesión exitoso:

• Modo pasivo. Muchos servidores (y la mayoría de configuraciones NAT/firewall) requieren el modo pasivo para transferencias de datos como listados de directorios y descargas. Actívelo con ftp_pasv() — pero solo después de que ftp_login() tenga éxito, nunca antes.
• Cifrado. El FTP simple envía el nombre de usuario y la contraseña en texto claro. Prefiera FTP sobre SSL/TLS abriendo la conexión con ftp_ssl_connect(); ftp_login() funciona exactamente igual en ese caso.

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

Errores comunes

• Nunca codifique las credenciales de forma fija en el código fuente que vaya a confirmar. Léalas desde variables de entorno o un archivo de configuración fuera del control de versiones.
• ftp_login() no conecta. Si le pasa una cadena de host en lugar de un identificador de conexión, obtendrá un TypeError. Siempre llame primero a ftp_connect().
• Un retorno true solo significa que la autenticación fue exitosa. No dice nada sobre los permisos — una subida posterior puede fallar igualmente si la cuenta carece de acceso de escritura.

Conclusión

ftp_login() autentica una conexión FTP abierta con un nombre de usuario y una contraseña, devolviendo true o false. Conecte siempre primero, compruebe el valor de retorno, active el modo pasivo después de iniciar sesión cuando sea necesario y prefiera una conexión cifrada en producción. Para el conjunto completo de funciones relacionadas, consulte la referencia FTP de PHP.

Práctica