Entendiendo la función PHP ftp_cdup()

Cuando automatizas transferencias de archivos por FTP, con frecuencia necesitas moverte por el árbol de directorios remoto antes de subir, descargar o listar archivos. La extensión FTP integrada de PHP ofrece un pequeño conjunto de funciones de navegación para esto, y ftp_cdup() es la que sube un nivel — el equivalente FTP de cd .. en la línea de comandos.

Este capítulo cubre qué hace ftp_cdup(), su sintaxis y valor de retorno, un ejemplo funcional completo, y los problemas que vale la pena conocer antes de usarla en producción.

¿Qué es ftp_cdup()?

ftp_cdup() cambia el directorio de trabajo actual en el servidor FTP remoto a su directorio padre. Hace exactamente una cosa: subir un nivel. Si estás en /var/www/html/uploads, llamar a ftp_cdup() una vez te deja en /var/www/html.

Es la contraparte de ftp_chdir(), que se mueve hacia dentro de un directorio con nombre. Usa ftp_chdir() para descender o saltar a una ruta, y ftp_cdup() para retroceder hacia la raíz.

ftp_cdup() solo afecta el directorio actual rastreado por tu sesión FTP. No mueve, copia ni elimina nada en el servidor.

Sintaxis

ftp_cdup(FTP\Connection $ftp): bool

Valor de retorno: true en caso de éxito, false en caso de fallo (por ejemplo, si ya estás en el directorio raíz o la conexión no está autenticada).

A partir de PHP 8.1, ftp_connect() devuelve un objeto FTP\Connection en lugar de un recurso. La función funciona de la misma manera; solo cambió la indicación de tipo.

Cómo usar ftp_cdup()

Antes de poder llamar a ftp_cdup(), debes:

1. Abrir una conexión con ftp_connect().
2. Autenticarte con ftp_login().
3. (Generalmente) cambiar al modo pasivo con ftp_pasv() para que las transferencias funcionen detrás de NAT/firewalls.

El ejemplo a continuación inicia sesión, desciende a un subdirectorio con ftp_chdir(), luego usa ftp_cdup() para subir de nuevo. Imprime el directorio de trabajo antes y después con ftp_pwd() para que puedas ver el efecto:

<?php

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

// Move into a sub-directory first.
ftp_chdir($ftp, 'uploads');
echo "Before: " . ftp_pwd($ftp) . PHP_EOL; // e.g. /uploads

// Step back up to the parent directory.
if (ftp_cdup($ftp)) {
    echo "After:  " . ftp_pwd($ftp) . PHP_EOL; // e.g. /
} else {
    echo "Failed to change to the parent directory" . PHP_EOL;
}

ftp_close($ftp);

Aquí nos conectamos, iniciamos sesión y habilitamos el modo pasivo. Luego descendemos a uploads, confirmamos la ubicación con ftp_pwd(), y llamamos a ftp_cdup() para volver al directorio padre. La comprobación if nos permite reaccionar cuando el movimiento falla en lugar de asumir que funcionó. Finalmente liberamos la conexión con ftp_close().

Problemas comunes

• Ya estás en la raíz. Llamar a ftp_cdup() desde la cima del árbol devuelve false. Siempre verifica el valor de retorno en lugar de asumir el éxito.
• Confundirla con una operación de archivos. ftp_cdup() solo cambia tu posición. Para eliminar o renombrar elementos remotos usa ftp_delete() o ftp_rename().
• Advertencias en caso de fallo. Una llamada fallida también emite un E-WARNING. Suprímelo o manéjalo según tu estrategia de errores, pero nunca confíes en la supresión en lugar de verificar el resultado boolean.
• Olvidar el modo pasivo. Si los listados o las transferencias se detienen después de navegar, probablemente omitiste ftp_pasv($ftp, true).

Conclusión

ftp_cdup() es el asistente de navegación más sencillo en el kit de herramientas FTP de PHP: mueve el directorio actual de la sesión un nivel hacia arriba y devuelve un boolean que indica si funcionó. Combínala con ftp_chdir() para descender y ftp_pwd() para confirmar dónde estás, y tendrás todo lo necesario para recorrer un árbol de directorios remoto de forma fiable.

Práctica