ftp_rename()

The PHP ftp_rename() Function

ftp_rename() renames a file or directory on a remote FTP server. Because FTP has no separate "move" command, this same function is also how you move a file to a different directory — you simply give a new path as the target name.

This page covers the syntax, parameters and return value, a complete connect-rename-disconnect example, how to move files with the same call, and the error-handling patterns you need for production code.

Syntax

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

Prior to PHP 8.1 the first argument was a resource returned by ftp_connect(); since PHP 8.1 it is an FTP\Connection object. Your code does not change — the variable still comes straight from ftp_connect().

Parameters

Return value

Returns true on success and false on failure. On failure, PHP also emits a warning describing the FTP server's response (for example, "550 oldname.txt: No such file or directory").

A complete example

You must open a connection and log in before calling ftp_rename(). The connection from ftp_connect() is passed to ftp_login(), then to every later FTP call:

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

We connect with ftp_connect(), authenticate with ftp_login(), rename with ftp_rename(), and finally release the connection with ftp_close(). Checking the return value of each step keeps the script from continuing in a broken state.

Moving a file to another directory

Because the second argument is a full path, giving ftp_rename() a target in a different directory moves the file instead of just renaming it. The destination directory must already exist — create it first with ftp_mkdir() if needed:

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

Error handling

ftp_rename() returns false (and raises a warning) when the source does not exist, the target already exists, or you lack permission. Always test the return value rather than assuming success:

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

Common causes of failure to check for:

• Source missing — the $from path does not exist on the server.
• Wrong working directory — relative paths resolve against the current FTP directory; use ftp_chdir() or absolute paths to avoid surprises.
• Permissions — the logged-in user lacks write access to the directory.
• Target exists — many servers refuse to overwrite an existing $to; delete it first with ftp_delete().

Summary

ftp_rename() renames — or moves — a file or directory on an FTP server, returning true on success and false on failure. Open the connection with ftp_connect(), authenticate with ftp_login(), check the return value of every call, and close the session with ftp_close() when finished.

Practice