ftp_nb_get()

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

Функция ftp_nb_get() загружает файл с FTP-сервера в неблокирующем режиме. В отличие от блокирующего аналога ftp_get(), который останавливает выполнение скрипта до завершения передачи файла, ftp_nb_get() почти сразу возвращает управление программе, позволяя выполнять другую работу, пока загрузка идёт в фоновом режиме.

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

Когда использовать неблокирующий режим

Сокращение «nb» в названии означает non-blocking (неблокирующий). Используйте ftp_nb_get() вместо ftp_get() в следующих случаях:

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

Для простой задачи «загрузить файл и подождать» проще использовать обычный ftp_get(). Компромисс состоит в том, что неблокирующий режим требует самостоятельного управления передачей в цикле с ftp_nb_continue().

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

Функция ftp_nb_get() инициирует асинхронную загрузку файла. Она принимает четыре параметра:

1. ftp_stream: идентификатор соединения, возвращаемый функцией ftp_connect().
2. local_file: локальный путь к файлу, в который будет сохранён загруженный файл.
3. remote_file: путь к удалённому файлу на FTP-сервере.
4. mode: режим передачи — FTP_ASCII или FTP_BINARY.

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

Функция возвращает одну из трёх констант:

Поскольку функция может вернуть управление до завершения загрузки, её почти всегда используют в паре с ftp_nb_continue() в цикле, который выполняется, пока результат равен FTP_MOREDATA.

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

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

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

int ftp_nb_get ( resource $ftp_stream , string $local_file , string $remote_file , int $mode [, int $resumepos = 0 ] )

Функция ftp_nb_get() принимает четыре обязательных параметра (ftp_stream, local_file, remote_file и mode) и один необязательный (resumepos). Параметр ftp_stream — это идентификатор соединения, возвращаемый функцией ftp_connect(). Параметр local_file — путь к локальному файлу, в который будет сохранён загруженный файл. Параметр remote_file — путь к удалённому файлу на FTP-сервере. Параметр mode задаёт режим передачи: FTP_ASCII или FTP_BINARY. Параметр resumepos задаёт позицию в удалённом файле, с которой начнётся загрузка. По умолчанию resumepos равен 0, то есть загрузка начнётся с начала файла.

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

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

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

<?php

// Set up an FTP connection
$conn = ftp_connect('ftp.example.com');

// Login with your FTP credentials
ftp_login($conn, 'username', 'password');

// Initiate an asynchronous FTP operation
$result = ftp_nb_get($conn, 'local_file.txt', 'remote_file.txt', FTP_BINARY);

if ($result === FTP_FAILED) {
    echo "Failed to download file from remote server.\n";
} else {
    // Continue the asynchronous FTP operation
    while ($result === FTP_MOREDATA) {
        // Do something else while waiting for the FTP operation to complete
        $result = ftp_nb_continue($conn);
    }
}

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

В этом примере устанавливается соединение с FTP-сервером с помощью ftp_connect(). Затем выполняется вход с использованием учётных данных FTP через ftp_login(). Асинхронная операция FTP инициируется с помощью ftp_nb_get(). Операция продолжается с помощью ftp_nb_continue() в цикле, который проверяет значение FTP_MOREDATA, и наконец соединение закрывается.

Возобновление прерванной загрузки

Необязательный пятый параметр resumepos позволяет продолжить частично загруженный файл, не начиная заново. Передайте смещение в байтах, с которого следует возобновить загрузку, — как правило, это размер уже имеющегося на диске файла:

Возобновление загрузки с помощью resumepos

<?php

$local = 'big-archive.zip';

// If a partial file already exists, resume from where it left off.
$resumePos = file_exists($local) ? filesize($local) : 0;

$result = ftp_nb_get($conn, $local, 'big-archive.zip', FTP_BINARY, $resumePos);

while ($result === FTP_MOREDATA) {
    $result = ftp_nb_continue($conn);
}

Это особенно полезно для больших файлов при нестабильных соединениях, когда не хочется повторно загружать уже полученные данные.

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

Всегда проверяйте возвращаемое значение. Функция ftp_nb_get() возвращает FTP_FAILED, когда не может начать (или продолжить) передачу, и ftp_nb_continue() также может вернуть FTP_FAILED в процессе передачи. Обрабатывайте оба случая:

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

<?php

$conn = ftp_connect('ftp.example.com');

if ($conn === false || !ftp_login($conn, 'username', 'password')) {
    exit("Could not connect or log in to the FTP server.\n");
}

$result = ftp_nb_get($conn, 'local_file.txt', 'remote_file.txt', FTP_BINARY);

// Drive the transfer to completion, watching for failure at every step.
while ($result === FTP_MOREDATA) {
    $result = ftp_nb_continue($conn);
}

if ($result === FTP_FINISHED) {
    echo "File downloaded successfully.\n";
} else {
    echo "Failed to download file from remote server.\n";
}

ftp_close($conn);

Проверяя соединение, вход и конечное состояние передачи по отдельности, вы можете точно определить, на каком этапе операция FTP завершилась с ошибкой.

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

• ftp_get() — блокирующая версия, которая загружает файл и ожидает завершения.
• ftp_nb_continue() — продолжает неблокирующую передачу, начатую функцией ftp_nb_get().
• ftp_nb_fget() — аналогична ftp_nb_get(), но записывает данные в открытый файловый указатель, а не по пути к файлу.
• ftp_connect() и ftp_login() — установка и аутентификация FTP-сессии.
• ftp_close() — закрытие соединения после завершения работы.

Заключение

Функция ftp_nb_get() загружает файлы с FTP-сервера в неблокирующем режиме, позволяя скрипту оставаться отзывчивым во время передачи. Используйте её совместно с ftp_nb_continue() в цикле, проверяйте возвращаемое значение на равенство FTP_FINISHED и FTP_FAILED, а параметр resumepos применяйте для восстановления прерванных загрузок.

Практика