ftp_rename()

Функция PHP ftp_rename()

ftp_rename() переименовывает файл или каталог на удалённом FTP-сервере. Поскольку протокол FTP не имеет отдельной команды «переместить», эта же функция используется для перемещения файла в другой каталог — достаточно указать новый путь в качестве целевого имени.

На этой странице рассматриваются синтаксис, параметры и возвращаемое значение, полный пример подключения, переименования и разрыва соединения, способ перемещения файлов тем же вызовом, а также шаблоны обработки ошибок, необходимые в производственном коде.

Синтаксис

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

До PHP 8.1 первым аргументом был resource, возвращаемый функцией ftp_connect(); начиная с PHP 8.1 это объект FTP\Connection. Код изменять не нужно — переменная по-прежнему поступает непосредственно из ftp_connect().

Параметры

Возвращаемое значение

Возвращает true в случае успеха и false в случае ошибки. При неудаче PHP также генерирует предупреждение с описанием ответа FTP-сервера (например, «550 oldname.txt: No such file or directory»).

Полный пример

Перед вызовом ftp_rename() необходимо открыть соединение и выполнить вход. Соединение, полученное от ftp_connect(), передаётся в ftp_login(), а затем во все последующие FTP-вызовы:

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

Подключаемся с помощью ftp_connect(), аутентифицируемся через ftp_login(), переименовываем с помощью ftp_rename() и, наконец, освобождаем соединение вызовом ftp_close(). Проверка возвращаемого значения каждого шага не позволяет скрипту продолжать работу в аварийном состоянии.

Перемещение файла в другой каталог

Поскольку второй аргумент — это полный путь, передав в ftp_rename() цель в другом каталоге, можно переместить файл, а не просто переименовать его. Целевой каталог должен уже существовать — при необходимости создайте его заранее с помощью ftp_mkdir():

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

Обработка ошибок

ftp_rename() возвращает false (и генерирует предупреждение), если источник не существует, цель уже существует или отсутствуют необходимые права. Всегда проверяйте возвращаемое значение, не рассчитывая на успех:

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

Распространённые причины ошибок, на которые следует обращать внимание:

• Источник отсутствует — путь $from не существует на сервере.
• Неверный рабочий каталог — относительные пути разрешаются относительно текущего каталога FTP; используйте ftp_chdir() или абсолютные пути, чтобы избежать неожиданностей.
• Права доступа — авторизованный пользователь не имеет прав на запись в каталог.
• Цель существует — многие серверы отказываются перезаписывать существующий $to; сначала удалите файл с помощью ftp_delete().

Итоги

ftp_rename() переименовывает или перемещает файл либо каталог на FTP-сервере, возвращая true в случае успеха и false в случае ошибки. Откройте соединение с помощью ftp_connect(), аутентифицируйтесь через ftp_login(), проверяйте возвращаемое значение каждого вызова и закрывайте сессию функцией ftp_close() по завершении работы.

Практика