ftp_connect()

La función PHP ftp_connect()

ftp_connect() abre una conexión de control hacia un servidor FTP y devuelve un identificador de conexión que todas las demás funciones FTP (ftp_login(), ftp_get(), ftp_put(), …) necesitan como primer argumento. Piensa en ella como marcar al servidor: la llamada solo abre el canal — no te autentica. Aún debes iniciar sesión con ftp_login() antes de poder transferir archivos.

Esta página cubre la sintaxis, los tres parámetros, un flujo de trabajo completo de conectar-iniciar sesión-cerrar, cómo gestionar fallos y cómo se relaciona ftp_connect() con su versión segura, ftp_ssl_connect().

Sintaxis

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

Valor de retorno. En caso de éxito obtienes un objeto de conexión — una instancia de FTP\Connection a partir de PHP 8.1, o un resource en versiones anteriores. En caso de fallo devuelve false, por lo que el resultado siempre debe verificarse antes de usarlo.

Nota: ftp_connect() establece una conexión sin cifrar — las credenciales y los datos viajan en texto plano. Para cualquier uso a través de internet público, es preferible usar ftp_ssl_connect() (FTPS).

Flujo de trabajo completo: conectar → iniciar sesión → cerrar

Una sesión típica abre la conexión, se autentica, realiza su trabajo y luego cierra el identificador:

<?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 paso corresponde a una función dedicada: ftp_login() autentica, ftp_pasv() activa el modo pasivo, ftp_put() y ftp_get() transfieren archivos, y ftp_close() cierra la conexión.

Gestionar una conexión fallida

Dado que ftp_connect() devuelve false en caso de fallo, trata un identificador ausente como un error grave — llamar a funciones FTP posteriores con false provoca un TypeError. Verifica tanto la conexión como el inicio de sesión:

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

Usa la comparación estricta === false en lugar de !$conn. Ambas se comportan igual para ftp_connect(), pero === false hace explícita tu intención y evita sorpresas cuando una función puede devolver legítimamente un valor vacío pero verdadero.

Problemas comunes

• La extensión FTP puede estar deshabilitada. Las funciones ftp_* requieren PHP compilado con --enable-ftp (o el paquete php-ftp). Si la portabilidad importa, protégete con if (!function_exists('ftp_connect')) { ... }.
• Modo pasivo. Si ftp_connect() y ftp_login() tienen éxito pero los listados o las transferencias se quedan bloqueados, el servidor probablemente está detrás de un cortafuegos — cambia al modo pasivo con ftp_pasv($conn, true) después de iniciar sesión.
• Conectar no es autenticarse. Un identificador devuelto solo significa que el canal TCP está abierto. Una contraseña incorrecta falla más tarde, en ftp_login().
• Sin prefijo ftp://. Pasa solo el nombre de host; el esquema está implícito en la función.

Para una descripción general de todo el conjunto de herramientas FTP, consulta la referencia de funciones PHP FTP.

Práctica