rename()

Introdução

A função PHP rename() renomeia um arquivo ou diretório — e como "renomear" é, na verdade, apenas alterar um caminho, a mesma função também move um arquivo ou diretório para outro local. Não existe uma função move() separada em PHP; você move renomeando para um novo caminho.

Esta página aborda a sintaxe e os parâmetros de rename(), quando usá-la (e quando não usar), os problemas comuns relacionados a permissões e movimentações entre sistemas de arquivos, além de exemplos completos e executáveis.

Sintaxe

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

A função retorna true em caso de sucesso e false em caso de falha. Em caso de falha, também emite um E_WARNING.

Como rename() Se Comporta

Algumas regras valem a pena conhecer antes de depender de rename():

• Ela sobrescreve. Se $to já existir e for um arquivo regular, rename() o sobrescreve (em sistemas Unix, de forma atômica). Verifique antes com file_exists() se não quiser substituir um arquivo existente.
• O diretório de destino já deve existir. rename() não cria pastas intermediárias. Use mkdir() primeiro se o diretório de destino estiver ausente.
• Permissões importam. O processo que executa o PHP (frequentemente o usuário do servidor web, por exemplo, www-data) precisa de permissão de escrita tanto no diretório de origem quanto no de destino — renomear altera entradas de diretório, não apenas o arquivo em si.
• Movimentações entre sistemas de arquivos podem falhar. Mover entre diferentes pontos de montagem ou drives não é garantido em todas as plataformas. Em caso de dúvida, use copy() para copiar o arquivo e depois unlink() para remover o original.

Exemplos

Exemplo 1: Renomeando um arquivo

<?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.";
}

Saída:

File renamed successfully.

Isso renomeia example.txt para new_example.txt no mesmo diretório.

Exemplo 2: Movendo um arquivo para outro diretório

<?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.";
}

Saída:

File moved successfully.

Como a parte do diretório do caminho mudou, o arquivo é movido para archive/.

Exemplo 3: Renomeação segura com verificações

Em código real, normalmente você valida antes de renomear para falhar com uma mensagem clara em vez de um aviso pouco informativo:

<?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).";
}

Isso protege contra as três razões mais comuns pelas quais rename() falha: uma origem ausente, um diretório de destino ausente e permissões insuficientes.

rename() vs. copy()

Use rename() quando quiser mover os dados — o caminho original desaparece e nada é duplicado, o que o torna rápido e atômico no mesmo sistema de arquivos. Use copy() quando precisar que o original permaneça no lugar, ou quando precisar mover entre sistemas de arquivos onde rename() pode não funcionar. Um padrão comum entre sistemas de arquivos é usar copy() seguido de unlink().

Funções Relacionadas

• copy() — duplicar um arquivo.
• unlink() — excluir um arquivo.
• file_exists() — verificar se um caminho existe antes de renomear.
• mkdir() — criar o diretório de destino.
• is_dir() / is_file() — distinguir arquivos de diretórios.

Conclusão

A função rename() renomeia e move arquivos e diretórios em PHP. Lembre-se de que ela sobrescreve um destino existente, requer que o diretório de destino já exista, precisa de permissões de escrita em ambos os lados e pode não funcionar entre sistemas de arquivos. Valide seus caminhos primeiro e recorra a copy() + unlink() quando uma movimentação simples não for possível.

Prática