ftp_nlist()

Функция PHP ftp_nlist()

ftp_nlist() возвращает плоский array имён файлов и подкаталогов внутри каталога на FTP-сервере. Это FTP-эквивалент команды nls/ls — вы получаете только имена, без информации о размере, правах доступа или дате.

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

Синтаксис

ftp_nlist(FTP\Connection $ftp, string $directory): array|false

Возвращаемое значение: array имён при успехе или false при ошибке.

Возвращаемые имена не включают префикс каталога — при просмотре /public_html/ вы получите index.php, а не /public_html/index.php. Если каталог пуст, возвращается пустой array [], что не то же самое, что false.

Полный пример

Прежде чем получить список файлов, необходимо открыть аутентифицированное соединение. Типичный порядок действий: ftp_connect() → ftp_login() → ftp_pasv() → ftp_nlist() → ftp_close():

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

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

// Enable passive mode (often required for directory listings)
ftp_pasv($conn, true);

// Get an array of filenames in the specified directory
$files = ftp_nlist($conn, '/public_html/');

// Output the array of filenames
print_r($files);

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

Каждый шаг защищён: выполнение прерывается, если подключение или вход завершаются неудачей. Включение пассивного режима с помощью ftp_pasv() очень важно — многие серверы (и большинство межсетевых экранов) требуют его перед получением списка каталога, поэтому отсутствие вызова ftp_pasv() — наиболее частая причина того, что ftp_nlist() молча возвращает false.

Для каталога, содержащего два файла, print_r() выведет примерно следующее:

Array
(
    [0] => index.php
    [1] => style.css
)

ftp_nlist() vs ftp_rawlist()

Используйте функцию, соответствующую вашим потребностям:

• ftp_nlist() возвращает только array имён — идеально для проверки «существует ли этот файл?» или перебора загрузок.
• ftp_rawlist() возвращает необработанный вывод команды LIST (по одной строке на запись, как ls -l), включая размеры, права доступа и даты — полезно, когда нужны эти метаданные и вы готовы их разбирать.

Если нужны только имена, предпочтительнее ftp_nlist(): её вывод одинаков на разных серверах, тогда как формат ftp_rawlist() зависит от типа FTP-сервера.

Обработка ошибок

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

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

<?php

// $conn is assumed to be established from the previous example
$file_list = ftp_nlist($conn, '/public_html/');

if ($file_list === false) {
    echo "Failed to list directory on remote server.\n";
}

ftp_close($conn);

Всегда используйте сравнение с === (строгое равенство). Нестрогая проверка if (!$file_list) будет воспринимать пустой каталог ([]) как ошибку, поскольку пустой array является ложным значением в PHP.

Типичные подводные камни

• Забытый пассивный режим. Вызывайте ftp_pasv($conn, true) после входа в систему, если получение списка возвращает false.
• Пустой array vs false. [] означает «каталог существует, но пуст»; false означает ошибку при получении списка. Различайте их с помощью ===.
• Имена без пути. Добавляйте каталог вручную, когда нужен полный путь: $dir . '/' . $name.
• Скрытые файлы. Некоторые серверы не включают файлы, начинающиеся с точки (.htaccess), в результат ftp_nlist(). Передайте -a в аргументе каталога (например, '-a /public_html/') на серверах, которые это поддерживают.

Заключение

ftp_nlist() — простейший способ получить имена файлов в удалённом каталоге. Сочетайте её с ftp_pasv() для надёжности, проверяйте возвращаемое значение с помощью === и обращайтесь к ftp_rawlist(), когда нужны метаданные файлов. Полный рабочий процесс FTP описан в обзоре PHP FTP.

Практика