ftp_raw()

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

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

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

FTP — текстовый протокол: клиенты отправляют короткие команды вроде SYST, PWD или FEAT, а сервер отвечает пронумерованными строками состояния (например, 215 UNIX Type: L8). Большинство PHP-функций для работы с FTP — таких как ftp_nlist(), ftp_get() и ftp_systype() — оборачивают одну из этих команд и разбирают ответ в удобное значение. ftp_raw() пропускает разбор и открывает доступ к протоколу напрямую.

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

1. ftp_stream — идентификатор соединения, возвращённый функцией ftp_connect().
2. command — строка FTP-команды для отправки (например, 'SYST' или 'PWD').

При успехе функция возвращает array строк, по одному элементу на каждую строку ответа, содержащих ответ сервера. При ошибке (например, при недопустимом соединении) возвращается false.

Когда стоит использовать ftp_raw()?

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

• Вам нужна команда, для которой в PHP нет обёртки (например, FEAT для получения возможностей сервера или пользовательская директива SITE).
• Вы отлаживаете и хотите увидеть точную строку состояния, которую возвращает сервер.
• Вы реализуете поведение протокола, которое высокоуровневый API не предоставляет.

Обратите внимание, что ftp_raw() предназначена только для команд управляющего канала. Она не может передавать данные файлов — команды вроде RETR или LIST требуют отдельного канала данных, поэтому для них используются ftp_get() или ftp_nlist().

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

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

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

ftp_raw(FTP\Connection $ftp, string $command): array

Параметр $ftp — это соединение, возвращённое функцией ftp_connect(), а $command — строка команды для отправки. Оба параметра обязательны.

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

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

<?php

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

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

// Ask the server what operating system it runs
$response = ftp_raw($conn, 'SYST');

// Output the server's raw response, one line per element
echo "Server response: " . implode("\n", $response) . "\n";
// e.g. Server response: 215 UNIX Type: L8

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

Здесь мы устанавливаем соединение с помощью ftp_connect() и проверяем его успешность, выполняем аутентификацию через ftp_login(), отправляем команду SYST с помощью ftp_raw() и выводим каждую строку ответа. 215 — это код ответа FTP; текст после него — ответ сервера. Наконец, мы освобождаем соединение с помощью ftp_close().

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

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

<?php

$response = ftp_raw($conn, 'SYST');

if ($response === false) {
    echo "Failed to send the raw command to the FTP server.\n";
} else {
    echo implode("\n", $response) . "\n";
}

ftp_close($conn);

Имейте в виду, что ненулевой array не гарантирует успешность самой команды — это лишь означает, что сервер ответил. Проверяйте код ответа (ведущее число в каждой строке, например 5xx для ошибок), если вам важно знать, была ли команда принята.

Заключение

Функция ftp_raw() даёт прямой доступ к управляющему каналу FTP, что неоценимо для команд, которые PHP не оборачивает (например, FEAT), а также для отладки. Для рутинного просмотра списков, загрузки и скачивания файлов используйте специализированные функции. Полный набор функций доступен в справочнике функций PHP FTP.

Практика