rename()

Introducción

La función rename() de PHP renombra un archivo o directorio — y como "renombrar" es simplemente cambiar una ruta, la misma función también mueve un archivo o directorio a una ubicación diferente. No existe una función move() separada en PHP; se mueve renombrando a una nueva ruta.

Esta página cubre la sintaxis y los parámetros de rename(), cuándo usarla (y cuándo no), los problemas comunes relacionados con permisos y movimientos entre sistemas de archivos, y ejemplos completos ejecutables.

Sintaxis

rename(string $from, string $to, ?resource $context = null): bool

La función devuelve true en caso de éxito y false en caso de error. En caso de error, también emite un E_WARNING.

Cómo se comporta rename()

Vale la pena conocer algunas reglas antes de depender de rename():

• Sobreescribe. Si $to ya existe y es un archivo normal, rename() lo sobreescribe (en sistemas similares a Unix, de forma atómica). Comprueba primero con file_exists() si no deseas sobrescribir un archivo existente.
• El directorio de destino debe existir previamente. rename() no crea carpetas intermedias. Usa mkdir() primero si falta el directorio de destino.
• Los permisos importan. El proceso que ejecuta PHP (normalmente el usuario del servidor web, p. ej. www-data) necesita permiso de escritura tanto en el directorio de origen como en el de destino — renombrar cambia las entradas del directorio, no solo el archivo en sí.
• Los movimientos entre sistemas de archivos pueden fallar. Mover entre diferentes puntos de montaje o unidades no está garantizado en todas las plataformas. En caso de duda, usa copy() para copiar el archivo y luego unlink() para eliminar el original.

Ejemplos

Ejemplo 1: Renombrar un archivo

<?php
// Create a file to work with so the example is self-contained.
file_put_contents('example.txt', 'hello');

if (rename('example.txt', 'new_example.txt')) {
    echo "File renamed successfully.";
} else {
    echo "Failed to rename the file.";
}

Salida:

File renamed successfully.

Esto renombra example.txt a new_example.txt en el mismo directorio.

Ejemplo 2: Mover un archivo a otro directorio

<?php
file_put_contents('example.txt', 'hello');

// Make sure the destination directory exists first.
if (!is_dir('archive')) {
    mkdir('archive');
}

if (rename('example.txt', 'archive/example.txt')) {
    echo "File moved successfully.";
} else {
    echo "Failed to move the file.";
}

Salida:

File moved successfully.

Como la parte del directorio de la ruta cambió, el archivo se mueve a archive/.

Ejemplo 3: Renombrado seguro con comprobaciones

En código real, normalmente se valida antes de renombrar para fallar con un mensaje claro en lugar de una advertencia poco informativa:

<?php
$from = 'report.txt';
$to   = 'reports/2026-report.txt';

if (!file_exists($from)) {
    echo "Source file does not exist.";
} elseif (!is_dir(dirname($to))) {
    echo "Destination directory is missing.";
} elseif (rename($from, $to)) {
    echo "Done.";
} else {
    echo "Rename failed (check permissions).";
}

Esto protege contra las tres razones más comunes por las que falla rename(): una fuente inexistente, un directorio de destino faltante y permisos insuficientes.

rename() vs. copy()

Usa rename() cuando quieras mover los datos — la ruta original desaparece y nada se duplica, lo que lo hace rápido y atómico en el mismo sistema de archivos. Usa copy() cuando necesites que el original permanezca en su lugar, o cuando debas mover entre sistemas de archivos donde rename() puede no funcionar. Un patrón común entre sistemas de archivos es copy() seguido de unlink().

Funciones Relacionadas

• copy() — duplicar un archivo.
• unlink() — eliminar un archivo.
• file_exists() — comprobar si existe una ruta antes de renombrar.
• mkdir() — crear el directorio de destino.
• is_dir() / is_file() — distinguir archivos de directorios.

Conclusión

La función rename() renombra y mueve archivos y directorios en PHP. Recuerda que sobreescribe un destino existente, requiere que el directorio de destino ya exista, necesita permisos de escritura en ambos extremos y puede no funcionar entre sistemas de archivos. Valida tus rutas primero, y recurre a copy() + unlink() cuando un movimiento simple no sea posible.

Práctica