ftp_get_option()

¿Qué es ftp_get_option()?

La función ftp_get_option() es una función integrada de PHP que recupera una sola opción de tiempo de ejecución de una conexión FTP abierta. Una opción de tiempo de ejecución es una configuración que controla el comportamiento del cliente FTP — por ejemplo, cuánto tiempo espera antes de que se agote el tiempo de espera, o si reanuda automáticamente las transferencias interrumpidas. Puedes leer estos ajustes con ftp_get_option() y modificarlos con su contraparte ftp_set_option().

Normalmente se recurre a ftp_get_option() cuando necesitas inspeccionar la configuración actual de una conexión antes de decidir qué hacer a continuación — por ejemplo, registrar el tiempo de espera activo o confirmar que la reanudación automática está habilitada antes de iniciar una descarga de gran tamaño.

La función acepta dos parámetros:

1. ftp — el identificador de conexión devuelto por ftp_connect() (un objeto FTP\Connection en PHP 8.1+, o un recurso en versiones anteriores).
2. option — la constante que nombra la opción a recuperar (por ejemplo, FTP_TIMEOUT_SEC).

La función devuelve un valor mixed según la opción consultada — un entero para FTP_TIMEOUT_SEC, o un boolean para las opciones de marca. Si el nombre de la opción es desconocido, PHP emite una advertencia y la función devuelve false.

Sintaxis de ftp_get_option()

La sintaxis de la función ftp_get_option() es la siguiente:

Sintaxis de ftp_get_option()

mixed ftp_get_option ( FTP\Connection|resource $ftp_stream , int $option )

Ambos parámetros son obligatorios. El parámetro $ftp_stream es el identificador de conexión devuelto por ftp_connect() (o ftp_ssl_connect()), y $option es una de las constantes FTP_* predefinidas descritas a continuación.

Opciones disponibles en ftp_get_option()

ftp_get_option() reconoce las siguientes constantes de opción. El tipo de retorno varía según la opción, lo cual es importante al verificar el resultado:

Nota: FTP_USEPASVADDRESS solo es relevante en modo pasivo. FTP_LISTEN, que puede aparecer en notas antiguas, no es una opción válida para ftp_get_option() y consultarla produce una advertencia y false.

Uso de ftp_get_option()

Para usar la función ftp_get_option(), primero debes establecer una conexión con el servidor FTP mediante la función ftp_connect(). A continuación se muestra un ejemplo:

Uso de ftp_get_option()

<?php

// Set up an FTP connection
$conn = ftp_connect('ftp.example.com');

// Login with your FTP credentials
ftp_login($conn, 'username', 'password');

// Retrieve the current timeout (in seconds)
$timeout = ftp_get_option($conn, FTP_TIMEOUT_SEC);
echo "Current timeout: {$timeout} seconds\n"; // Default: 90 seconds

// Check whether passive-address rewriting is enabled
$usePasv = ftp_get_option($conn, FTP_USEPASVADDRESS);
echo "Use PASV address: " . ($usePasv ? "yes" : "no") . "\n";

// Close the FTP connection
ftp_close($conn);

En este ejemplo, nos conectamos con ftp_connect(), nos autenticamos con ftp_login() y luego leemos dos opciones. El valor predeterminado de FTP_TIMEOUT_SEC en una conexión nueva es 90, por lo que la primera línea imprime Current timeout: 90 seconds. Finalmente, liberamos la conexión con ftp_close().

Manejo de errores en ftp_get_option()

Dado que FTP_AUTOSEEK y FTP_USEPASVADDRESS pueden devolver legítimamente el boolean false, nunca compruebes el resultado con == de forma no estricta — una marca deshabilitada parecería un error. Usa el operador de identidad estricta === para distinguir un error real de un valor false válido:

Manejo de errores en ftp_get_option()

<?php

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

$timeout = ftp_get_option($conn, FTP_TIMEOUT_SEC);

if ($timeout === false) {
    // The option name was invalid, or the connection is not usable
    echo "Failed to retrieve the option.\n";
} elseif ($timeout > 0) {
    echo "Timeout is set to {$timeout} seconds.\n";
} else {
    echo "No timeout is set.\n";
}

ftp_close($conn);

Aquí la comprobación estricta === false distingue un fallo real de recuperación de una opción cuyo valor real resulta ser 0 o false. Para opciones boolean como FTP_USEPASVADDRESS, guarda primero el resultado en una variable y luego compara con === antes de tratarlo como activado o desactivado.

Funciones relacionadas

• ftp_set_option() — cambia una opción de tiempo de ejecución (la contraparte de escritura de esta función).
• ftp_connect() — abre la conexión a la que se aplican estas opciones.
• ftp_pasv() — activa o desactiva el modo pasivo, que interactúa con FTP_USEPASVADDRESS.
• Descripción general de FTP en PHP — todas las funciones FTP de un vistazo.

Conclusión

La función ftp_get_option() permite leer la configuración de tiempo de ejecución de una conexión FTP abierta — especialmente el tiempo de espera de red y las marcas de reanudación automática y dirección pasiva. Recuerda que algunas opciones devuelven un boolean, por lo que siempre debes verificar el resultado con === para evitar confundir un false válido con un error.

Práctica