rename()

Введение

Функция PHP rename() переименовывает файл или директорию — и поскольку «переименование» — это по сути изменение пути, та же функция также перемещает файл или директорию в другое место. В PHP нет отдельной функции move(); перемещение выполняется путём переименования с новым путём.

На этой странице рассматриваются синтаксис и параметры rename(), когда её использовать (а когда — нет), распространённые проблемы с правами доступа и перемещением между разными файловыми системами, а также полные рабочие примеры.

Синтаксис

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

Функция возвращает true при успехе и false при ошибке. При ошибке также генерируется предупреждение E_WARNING.

Поведение rename()

Перед использованием rename() стоит знать несколько правил:

• Перезапись. Если $to уже существует и является обычным файлом, rename() перезапишет его (в Unix-подобных системах — атомарно). Проверьте заранее с помощью file_exists(), если не хотите перезаписать существующий файл.
• Директория назначения должна существовать. rename() не создаёт промежуточные папки. Используйте mkdir() заранее, если целевая директория отсутствует.
• Права доступа важны. Процессу, выполняющему PHP (как правило, пользователю веб-сервера, например www-data), нужны права на запись как в исходной директории, так и в целевой — переименование изменяет записи директорий, а не только сам файл.
• Перемещение между разными файловыми системами может завершиться ошибкой. Перемещение между разными точками монтирования или дисками не гарантируется на всех платформах. В сомнительных случаях лучше copy() файл, а затем unlink() оригинал.

Примеры

Пример 1: Переименование файла

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

Вывод:

File renamed successfully.

Это переименовывает example.txt в new_example.txt в той же директории.

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

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

Вывод:

File moved successfully.

Поскольку часть пути с директорией изменилась, файл перемещается в archive/.

Пример 3: Безопасное переименование с проверками

В реальном коде обычно выполняют валидацию перед переименованием, чтобы при ошибке выдавалось понятное сообщение, а не бесполезное предупреждение:

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

Это защищает от трёх наиболее распространённых причин сбоя rename(): отсутствующего источника, отсутствующей целевой директории и недостаточных прав доступа.

rename() vs. copy()

Используйте rename(), когда хотите переместить данные — исходный путь исчезает и ничего не дублируется, что делает операцию быстрой и атомарной в пределах одной файловой системы. Используйте copy(), когда оригинал должен остаться на месте, или когда нужно переместить файл между файловыми системами, где rename() может не работать. Распространённый паттерн для межфайловых перемещений: copy(), а затем unlink().

Связанные функции

• copy() — скопировать файл.
• unlink() — удалить файл.
• file_exists() — проверить существование пути перед переименованием.
• mkdir() — создать целевую директорию.
• is_dir() / is_file() — различать файлы и директории.

Заключение

Функция rename() в PHP позволяет как переименовывать, так и перемещать файлы и директории. Помните: она перезаписывает существующий файл назначения, требует предварительного существования целевой директории, нуждается в правах на запись с обеих сторон и может не работать при перемещении между файловыми системами. Проверяйте пути заранее и в случае невозможности простого перемещения используйте copy() + unlink().

Практика