ftp_site()

Понимание PHP-функции ftp_site()

Функция ftp_site() — это встроенная PHP-функция, которая отправляет команду SITE на FTP-сервер. SITE — универсальная FTP-команда для инструкций, выходящих за рамки стандартного FTP-протокола: таких, которые каждый производитель сервера реализует по-своему, например изменение прав доступа к файлам, настройка тайм-аута простоя или выполнение специфических для сервера задач обслуживания.

Поскольку смысл команды SITE полностью определяется удалённым сервером, ftp_site() — это аварийный выход, к которому прибегают тогда, когда ни одна из стандартных PHP FTP-функций не подходит для решаемой задачи. В этой статье объясняется, что делает функция, когда её следует использовать (и когда не следует) и как правильно обрабатывать её результат.

Для работы с ней сначала откройте соединение с помощью ftp_connect() и выполните аутентификацию через ftp_login(). Полный список функций семейства FTP см. в разделе Обзор PHP FTP.

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

Функция принимает два параметра:

1. ftp — FTP-соединение, возвращённое функцией ftp_connect() (или ftp_ssl_connect()).
2. command — строка с командой SITE для отправки, без ключевого слова SITE в начале (PHP добавляет его автоматически).

Функция возвращает true, если сервер принял команду, и false в случае ошибки. Результат true означает лишь то, что сервер принял команду — это не гарантирует успешности самого действия (например, изменения прав доступа), поскольку поведение SITE определяется сервером.

Синтаксис ftp_site()

Синтаксис функции ftp_site() выглядит следующим образом:

Синтаксис ftp_site()

ftp_site(FTP\Connection $ftp, string $command): bool

Начиная с PHP 8.1 первый аргумент является объектом FTP\Connection (в более ранних версиях это был ресурс). Аргумент command — инструкция SITE для отправки, например CHMOD 644 file.txt. Передаётся только часть после SITE; PHP автоматически добавляет ключевое слово.

Использование ftp_site()

Чтобы использовать функцию ftp_site(), сначала необходимо установить соединение с FTP-сервером с помощью функции ftp_connect(). Пример:

Использование ftp_site()

<?php

// Set up an FTP connection
$conn = @ftp_connect('ftp.example.com');
if (!$conn) {
    die('Could not connect to server.');
}

// Login with your FTP credentials
if (!ftp_login($conn, 'username', 'password')) {
    die('Login failed.');
}

// Send the SITE command
ftp_site($conn, 'CHMOD 755 /public_html/index.php');

// Close the FTP connection
ftp_close($conn);

В этом примере мы устанавливаем соединение с помощью ftp_connect(), выполняем аутентификацию через ftp_login(), отправляем SITE CHMOD 755 для изменения прав доступа к index.php и закрываем соединение с помощью ftp_close().

Примечание: Команды SITE специфичны для конкретных серверов. SITE CHMOD поддерживается не на всех FTP-серверах. Для стандартного изменения прав доступа к файлам предпочтительнее использовать специализированную функцию ftp_chmod(), которая является переносимой и возвращает новое значение прав доступа. Обращайтесь к ftp_site() только для тех действий, для которых нет отдельной FTP-функции.

Распространённые команды SITE

Конкретный набор поддерживаемых команд зависит от серверного программного обеспечения (ProFTPD, vsftpd, Pure-FTPd и др.), однако некоторые из них широко доступны:

В случае сомнений выполните SITE HELP, чтобы узнать, какие команды поддерживает конкретный сервер:

Обнаружение поддерживаемых команд SITE

<?php

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

if (ftp_site($conn, 'HELP')) {
    echo "Server accepted the SITE HELP command.\n";
}

ftp_close($conn);

Обработка ошибок в ftp_site()

При использовании функции ftp_site() важно правильно обрабатывать ошибки. Если функция возвращает false, это означает, что операция не была выполнена успешно. Пример обработки ошибок:

Обработка ошибок в ftp_site()

<?php

if (!ftp_site($conn, 'CHMOD 755 /public_html/index.php')) {
    echo "Failed to send SITE command.\n";
}

ftp_close($conn);

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

ftp_site() vs. ftp_raw() и ftp_exec()

ftp_site() тесно связана с двумя другими функциями «отправки необработанной инструкции», и важно знать, в каких случаях выбирать каждую из них:

• ftp_site() — отправляет одну команду SITE и возвращает boolean. Используйте для специфических серверных действий, таких как CHMOD или UMASK.
• ftp_raw() — отправляет любую необработанную FTP-команду (не только SITE) и возвращает полный ответ сервера в виде array, что позволяет самостоятельно прочитать код статуса. Используйте, когда необходимо проанализировать ответ.
• ftp_exec() — запускает программу на сервере через SITE EXEC там, где это поддерживается. Используйте только на серверах, которые вы контролируете и которым доверяете.

Для повседневных операций (загрузка, скачивание, листинг, переименование) предпочтительнее использовать специализированные функции, описанные в Обзоре PHP FTP; они более переносимы, чем команды SITE, составленные вручную.

Заключение

Функция ftp_site() позволяет отправлять специфические для сервера команды SITE в тех случаях, когда ни одна стандартная PHP FTP-функция не подходит. Всегда проверяйте возвращаемое значение, помните, что успешная отправка команды не означает успешного выполнения действия, и используйте переносимые функции, такие как ftp_chmod(), когда они доступны.

Практика