Функция PHP ftp_cdup() — подробное руководство

Когда вы автоматизируете передачу файлов по FTP, нередко приходится перемещаться по дереву удалённых директорий перед загрузкой, скачиванием или просмотром файлов. Встроенное расширение FTP в PHP предоставляет небольшой набор навигационных функций, и ftp_cdup() — та из них, что перемещает вверх на один уровень: FTP-аналог команды cd .. в командной строке.

В этой главе рассматривается, что делает ftp_cdup(), её синтаксис и возвращаемое значение, полный рабочий пример, а также подводные камни, о которых стоит знать перед использованием в рабочей среде.

Что такое ftp_cdup()?

ftp_cdup() меняет текущую рабочую директорию на удалённом FTP-сервере на её родительскую директорию. Функция делает ровно одно: поднимается на один уровень вверх. Если вы находитесь в /var/www/html/uploads, один вызов ftp_cdup() переместит вас в /var/www/html.

Это противоположность функции ftp_chdir(), которая переходит в именованную директорию. Используйте ftp_chdir() для спуска или перехода по пути, а ftp_cdup() — чтобы подняться обратно к корню.

ftp_cdup() влияет только на текущую директорию, отслеживаемую вашей FTP-сессией. Она не перемещает, не копирует и не удаляет ничего на сервере.

Синтаксис

ftp_cdup(FTP\Connection $ftp): bool

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

Начиная с PHP 8.1, ftp_connect() возвращает объект FTP\Connection, а не ресурс. Функция работает так же; изменилась только подсказка типа.

Как использовать ftp_cdup()

Перед вызовом ftp_cdup() необходимо:

1. Открыть соединение с помощью ftp_connect().
2. Пройти аутентификацию с помощью ftp_login().
3. (Как правило) переключиться в пассивный режим с помощью ftp_pasv(), чтобы передачи работали за NAT/брандмауэрами.

Пример ниже выполняет вход, спускается в поддиректорию с помощью ftp_chdir(), затем использует ftp_cdup() для подъёма обратно. Текущая директория выводится до и после вызова с помощью ftp_pwd(), чтобы наглядно увидеть результат:

<?php

$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'username', 'password');
ftp_pasv($ftp, true);

// Move into a sub-directory first.
ftp_chdir($ftp, 'uploads');
echo "Before: " . ftp_pwd($ftp) . PHP_EOL; // e.g. /uploads

// Step back up to the parent directory.
if (ftp_cdup($ftp)) {
    echo "After:  " . ftp_pwd($ftp) . PHP_EOL; // e.g. /
} else {
    echo "Failed to change to the parent directory" . PHP_EOL;
}

ftp_close($ftp);

Здесь мы подключаемся, авторизуемся и включаем пассивный режим. Затем спускаемся в uploads, проверяем местоположение с помощью ftp_pwd() и вызываем ftp_cdup(), чтобы вернуться к родительской директории. Проверка if позволяет обработать ошибку перехода, не полагаясь на предположение об успехе. В конце освобождаем соединение с помощью ftp_close().

Распространённые ошибки

• Вы уже находитесь в корне. Вызов ftp_cdup() из вершины дерева возвращает false. Всегда проверяйте возвращаемое значение, не предполагая успех.
• Путаница с файловой операцией. ftp_cdup() меняет только вашу позицию. Для удаления или переименования удалённых элементов используйте ftp_delete() или ftp_rename().
• Предупреждения при ошибке. Неудачный вызов также генерирует E-WARNING. Подавляйте или обрабатывайте его в соответствии со своей стратегией обработки ошибок, но никогда не полагайтесь на подавление вместо проверки boolean-результата.
• Забытый пассивный режим. Если листинги или передачи зависают после навигации, скорее всего, вы пропустили ftp_pasv($ftp, true).

Заключение

ftp_cdup() — простейшая навигационная функция в FTP-инструментарии PHP: она перемещает текущую директорию сессии на один уровень вверх и возвращает boolean, сообщая, успешно ли это выполнено. В сочетании с ftp_chdir() для спуска и ftp_pwd() для проверки текущей позиции у вас есть всё необходимое для надёжной навигации по удалённому дереву директорий.

Практика