ftp_set_option()

La función ftp_set_option() configura el comportamiento en tiempo de ejecución de una conexión FTP ya abierta en PHP. Permite ajustar cómo se comporta el cliente FTP — tiempos de espera de conexión, direccionamiento en modo pasivo y si las descargas buscan automáticamente al reanudar — sin necesidad de cerrar y reestablecer la conexión.

Esta página explica qué hace cada opción, cuándo deberías usarla y cómo establecerlas de forma segura. Se asume que ya tienes una conexión abierta mediante ftp_connect() (o ftp_ssl_connect()) y has iniciado sesión con ftp_login().

Sintaxis

ftp_set_option(FTP\Connection $ftp, int $option, mixed $value): bool

La función devuelve true en caso de éxito, o false si la opción no se pudo establecer (por ejemplo, cuando $value tiene el tipo incorrecto para el $option elegido).

Nota: En PHP 8.1+ el primer argumento es un objeto FTP\Connection. En PHP 8.0 y anteriores es un resource devuelto por ftp_connect(). El nombre de la función y el comportamiento son idénticos en ambos casos.

Uso básico

Abre una conexión, inicia sesión y luego establece la opción. Normalmente las opciones se configuran justo después del inicio de sesión, antes de comenzar a transferir archivos, para que cada transferencia utilice el nuevo comportamiento.

<?php

// Open a connection to the FTP server
$ftp = ftp_connect('ftp.example.com');

if (!$ftp) {
    die('Could not connect to FTP server.');
}

// Authenticate
ftp_login($ftp, 'username', 'password');

// Abort any network operation that stalls for more than 30 seconds
ftp_set_option($ftp, FTP_TIMEOUT_SEC, 30);

// ... transfers happen here ...

ftp_close($ftp);

Aquí nos conectamos con ftp_connect(), nos autenticamos con ftp_login(), reducimos el tiempo de espera de red a 30 segundos con ftp_set_option() y finalmente cerramos la conexión con ftp_close().

Opciones disponibles

ftp_set_option() acepta las siguientes constantes de opción:

FTP_TIMEOUT_SEC y FTP_USEPASVADDRESS son las dos opciones que ajustarás con más frecuencia en código real: la primera cuando las transferencias superan el tiempo de espera, la segunda cuando el modo pasivo falla detrás de un firewall.

Puedes leer el valor actual de cualquiera de estas opciones con ftp_get_option().

Desactivar la búsqueda automática

Una razón habitual para llamar a ftp_set_option() es desactivar FTP_AUTOSEEK. Por defecto, al reanudar una descarga con un desplazamiento distinto de cero se busca en el archivo local. Si quieres que cada descarga sobreescriba desde el byte cero, desactívalo:

<?php

$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'username', 'password');

// Force full transfers instead of resuming from an offset
ftp_set_option($ftp, FTP_AUTOSEEK, false);

ftp_close($ftp);

Manejo de errores

ftp_set_option() devuelve false (y emite una advertencia) cuando el valor no coincide con la opción — por ejemplo, al pasar una string donde se espera un int. Comprueba el valor de retorno para que una opción ignorada silenciosamente no te sorprenda después:

<?php

$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'username', 'password');

if (!ftp_set_option($ftp, FTP_TIMEOUT_SEC, 30)) {
    echo "Failed to set the FTP timeout option.\n";
}

ftp_close($ftp);

Trabaja siempre con una conexión activa: pasar una conexión cerrada o inválida produce una advertencia en lugar de un false limpio, así que establece tus opciones antes de llamar a ftp_close().

Conclusión

ftp_set_option() ajusta cómo se comporta una conexión FTP abierta — principalmente su tiempo de espera de red y el manejo de direcciones en modo pasivo detrás de NAT. Establece las opciones inmediatamente después de ftp_login(), comprueba el valor de retorno y usa ftp_get_option() para confirmar qué está en vigor actualmente. Para el flujo de trabajo FTP completo, consulta la descripción general de PHP FTP.

Práctica