ftp_rename()

La función ftp_rename() de PHP

ftp_rename() renombra un archivo o directorio en un servidor FTP remoto. Como FTP no tiene un comando separado de "mover", esta misma función es la que se usa para mover un archivo a un directorio diferente: simplemente se indica una nueva ruta como nombre de destino.

Esta página cubre la sintaxis, los parámetros y el valor de retorno, un ejemplo completo de conexión-renombrado-desconexión, cómo mover archivos con la misma llamada y los patrones de manejo de errores necesarios para código en producción.

Sintaxis

ftp_rename(FTP\Connection $ftp, string $from, string $to): bool

Antes de PHP 8.1 el primer argumento era un resource devuelto por ftp_connect(); desde PHP 8.1 es un objeto FTP\Connection. El código no cambia: la variable sigue viniendo directamente de ftp_connect().

Parámetros

Valor de retorno

Devuelve true en caso de éxito y false en caso de fallo. Al fallar, PHP también emite una advertencia que describe la respuesta del servidor FTP (por ejemplo, "550 oldname.txt: No such file or directory").

Un ejemplo completo

Se debe abrir una conexión e iniciar sesión antes de llamar a ftp_rename(). La conexión de ftp_connect() se pasa a ftp_login() y luego a cada llamada FTP posterior:

<?php

// Open an FTP connection (returns false on failure)
$ftp = ftp_connect('ftp.example.com');

if ($ftp === false) {
    exit("Could not connect to the FTP server.\n");
}

// Authenticate
if (!ftp_login($ftp, 'username', 'password')) {
    ftp_close($ftp);
    exit("Login failed.\n");
}

// Rename the file
if (ftp_rename($ftp, '/public_html/oldname.txt', '/public_html/newname.txt')) {
    echo "File renamed successfully.\n";
} else {
    echo "File rename failed.\n";
}

// Always close the connection when you are done
ftp_close($ftp);

Se conecta con ftp_connect(), se autentica con ftp_login(), se renombra con ftp_rename() y finalmente se libera la conexión con ftp_close(). Verificar el valor de retorno de cada paso evita que el script continúe en un estado incorrecto.

Mover un archivo a otro directorio

Dado que el segundo argumento es una ruta completa, si se le pasa a ftp_rename() un destino en un directorio diferente, el archivo se mueve en lugar de simplemente renombrarse. El directorio de destino debe existir previamente; créelo antes con ftp_mkdir() si es necesario:

<?php
// Move report.csv from /uploads into /archive (and rename it in the same call)
if (ftp_rename($ftp, '/uploads/report.csv', '/archive/report-2024.csv')) {
    echo "File archived.\n";
} else {
    echo "Move failed — does /archive exist?\n";
}

Manejo de errores

ftp_rename() devuelve false (y genera una advertencia) cuando el origen no existe, el destino ya existe o no se tienen los permisos necesarios. Siempre compruebe el valor de retorno en lugar de asumir que la operación fue exitosa:

<?php

if (!ftp_rename($ftp, '/public_html/oldname.txt', '/public_html/newname.txt')) {
    // Suppress the built-in warning and react to the failure yourself
    echo "Failed to rename file.\n";
}

ftp_close($ftp);

Causas comunes de fallo que conviene verificar:

• Origen inexistente — la ruta $from no existe en el servidor.
• Directorio de trabajo incorrecto — las rutas relativas se resuelven respecto al directorio FTP actual; use ftp_chdir() o rutas absolutas para evitar sorpresas.
• Permisos — el usuario autenticado no tiene acceso de escritura al directorio.
• Destino existente — muchos servidores rechazan sobrescribir un $to existente; elimínelo primero con ftp_delete().

Resumen

ftp_rename() renombra, o mueve, un archivo o directorio en un servidor FTP, devolviendo true en caso de éxito y false en caso de fallo. Abra la conexión con ftp_connect(), autentíquese con ftp_login(), compruebe el valor de retorno de cada llamada y cierre la sesión con ftp_close() al terminar.

Práctica