ftp_rename()

A Função PHP ftp_rename()

ftp_rename() renomeia um arquivo ou diretório em um servidor FTP remoto. Como o FTP não possui um comando separado de "mover", essa mesma função também é usada para mover um arquivo para um diretório diferente — basta fornecer um novo caminho como nome de destino.

Esta página aborda a sintaxe, os parâmetros e o valor de retorno, um exemplo completo de conexão-renomeação-desconexão, como mover arquivos com a mesma chamada, e os padrões de tratamento de erros necessários para código em produção.

Sintaxe

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

Antes do PHP 8.1, o primeiro argumento era um resource retornado por ftp_connect(); desde o PHP 8.1, é um objeto FTP\Connection. O código não muda — a variável ainda vem diretamente de ftp_connect().

Parâmetros

Valor de retorno

Retorna true em caso de sucesso e false em caso de falha. Em caso de falha, o PHP também emite um aviso descrevendo a resposta do servidor FTP (por exemplo, "550 oldname.txt: No such file or directory").

Um exemplo completo

É necessário abrir uma conexão e fazer login antes de chamar ftp_rename(). A conexão de ftp_connect() é passada para ftp_login() e depois para todas as chamadas FTP subsequentes:

<?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);

Conectamos com ftp_connect(), autenticamos com ftp_login(), renomeamos com ftp_rename(), e por fim liberamos a conexão com ftp_close(). Verificar o valor de retorno de cada etapa impede que o script continue em um estado inválido.

Movendo um arquivo para outro diretório

Como o segundo argumento é um caminho completo, fornecer a ftp_rename() um destino em um diretório diferente move o arquivo em vez de apenas renomeá-lo. O diretório de destino deve existir previamente — crie-o primeiro com ftp_mkdir() se necessário:

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

Tratamento de erros

ftp_rename() retorna false (e gera um aviso) quando a origem não existe, o destino já existe ou não há permissão suficiente. Sempre verifique o valor de retorno em vez de assumir o sucesso:

<?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 comuns de falha a verificar:

• Origem ausente — o caminho $from não existe no servidor.
• Diretório de trabalho incorreto — caminhos relativos são resolvidos em relação ao diretório FTP atual; use ftp_chdir() ou caminhos absolutos para evitar surpresas.
• Permissões — o usuário autenticado não tem acesso de escrita ao diretório.
• Destino existente — muitos servidores recusam sobrescrever um $to existente; exclua-o primeiro com ftp_delete().

Resumo

ftp_rename() renomeia — ou move — um arquivo ou diretório em um servidor FTP, retornando true em caso de sucesso e false em caso de falha. Abra a conexão com ftp_connect(), autentique com ftp_login(), verifique o valor de retorno de cada chamada e encerre a sessão com ftp_close() ao terminar.

Prática