ftp_rawlist()

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

Функция ftp_rawlist() возвращает подробный список файлов директории на FTP-сервере. Каждый элемент возвращаемого array — это одна строка необработанного вывода команды LIST сервера — тот же текст, который вы видите в терминальном FTP-клиенте, включая права доступа, владельца, размер и дату изменения.

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

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

ftp_rawlist() принимает два обязательных параметра и один необязательный:

1. ftp_stream — объект соединения (PHP 8.1+) или ресурс, возвращаемый ftp_connect() (или ftp_ssl_connect()).
2. directory — директория для листинга.
3. recursive (необязательный) — установите в true для рекурсивного обхода поддиректорий.

При успехе функция возвращает array строк, где каждая строка — одна необработанная строка вывода; при ошибке (или для пустой нечитаемой директории) возвращает false.

Важно понимать, что этот вывод не стандартизирован. Это то, что выдаёт команда LIST сервера, поэтому его формат зависит от операционной системы и конфигурации сервера. Unix-подобный сервер обычно возвращает строки, похожие на вывод ls -l:

drwxr-xr-x   2 owner group        4096 Jun 21 10:00 images
-rw-r--r--   1 owner group       10240 Jun 20 14:32 index.html

Серверы в стиле Windows/DOS возвращают совершенно иной формат. Из-за этого ftp_rawlist() даёт полные сведения ценой необходимости самостоятельно разбирать свободный текст. Сравните с:

• ftp_nlist() — возвращает простой array только с именами файлов.
• ftp_mlsd() — возвращает машиночитаемый структурированный листинг (предпочтительно, когда сервер поддерживает команду MLSD).

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

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

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

array ftp_rawlist ( FTP\Connection|resource $ftp_stream , string $directory [, bool $recursive = false ] )

Функция ftp_rawlist() принимает два обязательных параметра: ftp_stream и directory. Параметр ftp_stream — это идентификатор соединения, возвращаемый функцией ftp_connect(), а параметр directory — директория для листинга. Функция также имеет один необязательный параметр recursive, позволяющий указать, нужно ли выводить поддиректории.

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

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

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

<?php

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

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

// Get a detailed listing of the directory
$listing = ftp_rawlist($conn, '/public_html');

// Output the listing to the console
if ($listing) {
    foreach ($listing as $item) {
        echo $item . "\n";
    }
}

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

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

Совет — пассивный режим: Многие сети и межсетевые экраны блокируют канал данных в активном режиме, который использует ftp_rawlist() для получения листинга, из-за чего функция зависает или возвращает false. Если это происходит, включите пассивный режим с помощью ftp_pasv($conn, true) после входа в систему.

Примечание о безопасности: Стандартный FTP передаёт учётные данные и данные в открытом виде. Для производственных сред рассмотрите использование ftp_ssl_connect() для явного FTP через TLS или переключитесь на SFTP (через расширение ssh2) для зашифрованной передачи данных.

Разбор необработанного листинга

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

Разбор необработанного листинга в стиле Unix

<?php

// One line of typical ftp_rawlist() output:
$line = '-rw-r--r--   1 owner group       10240 Jun 20 14:32 index.html';

// Split on runs of whitespace, limited so the name stays intact.
$parts = preg_split('/\s+/', $line, 9);

$type        = $parts[0][0] === 'd' ? 'directory' : 'file';
$permissions = $parts[0];
$size        = (int) $parts[4];
$name        = $parts[8];

echo "Name:        $name\n";
echo "Type:        $type\n";
echo "Size:        $size bytes\n";
echo "Permissions: $permissions\n";
?>

Выводит:

Name:        index.html
Type:        file
Size:        10240 bytes
Permissions: -rw-r--r--

Если ваш сервер поддерживает это, предпочтительнее использовать ftp_mlsd(), которая возвращает данные уже структурированными, избавляя от хрупкого разбора строк.

Рекурсивный листинг поддиректорий

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

<?php

// Assuming $conn is an active FTP connection
$listing = ftp_rawlist($conn, '/public_html', true);

foreach ($listing as $line) {
    if ($line === '' || str_ends_with($line, ':')) {
        // Skip blank separators and "/path/to/dir:" headers
        continue;
    }
    echo $line . "\n";
}
?>

Обратите внимание, что не каждый FTP-сервер поддерживает флаг рекурсии, а обход глубокого дерева может выполняться медленно, поэтому протестируйте это на целевом сервере.

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

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

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

<?php

// Assuming $conn is an active FTP connection
$listing = ftp_rawlist($conn, '/public_html');

if (!$listing) {
    echo "Failed to get directory listing from FTP server.\n";
}

ftp_close($conn);
?>

Правильно обрабатывая ошибки и проверяя возвращаемое значение функции, вы обеспечите успешность FTP-операций с использованием функции ftp_rawlist().

Заключение

ftp_rawlist() — функция для случаев, когда нужны полные метаданные файлов: права доступа, владелец, размер и дата, а не только имена. Компромисс состоит в том, что её вывод — это необработанный, зависящий от ОС текст команды LIST, поэтому планируйте его разбор (или используйте структурированный ftp_mlsd(), если доступен). Всегда проверяйте возвращаемое значение, включайте пассивный режим за межсетевым экраном и предпочитайте зашифрованное соединение для производственной среды.

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

• ftp_nlist() — список только имён файлов
• ftp_mlsd() — структурированный машиночитаемый листинг
• ftp_connect() / ftp_login() — открытие и аутентификация сессии
• ftp_get() — скачивание файла после его обнаружения
• ftp_close() — закрытие соединения

Practice