ftp_nb_fput()

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

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

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

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

Функция ftp_nb_fput() загружает файл на FTP-сервер в неблокирующем режиме. Она принимает четыре обязательных параметра и один необязательный:

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

Функция возвращает одну из следующих констант: FTP_SUCCESS (загрузка завершена), FTP_MOREDATA (требуется читать больше данных) или FTP_FAILED (произошла ошибка).

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

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

int ftp_nb_fput ( resource $ftp_stream , string $remote_file , resource $handle , int $mode [, int $startpos = 0 ] )

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

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

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

<?php

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

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

// Enable passive mode to prevent transfer issues
ftp_pasv($conn, true);

// Open a file for reading
$handle = fopen('local_file.txt', 'r');

// Initiate an asynchronous FTP operation
$res = ftp_nb_fput($conn, 'remote_file.txt', $handle, FTP_BINARY);

// Continue the asynchronous FTP operation
while ($res == FTP_MOREDATA) {
    $res = ftp_nb_continue($conn);
}

// Check for errors
if ($res != FTP_FAILED && $res != FTP_SUCCESS) {
    echo "FTP upload failed.\n";
}

// Close the file
fclose($handle);

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

В этом примере мы устанавливаем соединение с FTP-сервером, входим с нашими учётными данными и включаем пассивный режим с помощью ftp_pasv(), чтобы избежать распространённых проблем с передачей за межсетевыми экранами. Мы открываем локальный файл для чтения, затем вызываем ftp_nb_fput(), чтобы начать загрузку. Ключевая деталь — цикл while: пока ftp_nb_fput() (или последующие вызовы) возвращает FTP_MOREDATA, мы продолжаем передачу с помощью ftp_nb_continue(). В реальном приложении каждая итерация этого цикла — это место, где можно выполнять другую работу, поскольку передача является неблокирующей.

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

Важно правильно обрабатывать ошибки при использовании функции ftp_nb_fput(). Функция возвращает конкретные константы, а не boolean-значение, поэтому для обнаружения ошибок необходимо проверять FTP_FAILED. Вот пример обработки ошибок:

<?php

// Assume $conn is already established and logged in
$handle = fopen('local_file.txt', 'r');
$res = ftp_nb_fput($conn, 'remote_file.txt', $handle, FTP_BINARY);

if ($res == FTP_FAILED) {
    echo "Failed to initiate upload.\n";
}

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

if ($res == FTP_FAILED) {
    echo "Failed to complete upload.\n";
}

fclose($handle);
ftp_close($conn);

Правильно обрабатывая ошибки и проверяя возвращаемые константы как ftp_nb_fput(), так и ftp_nb_continue(), вы можете гарантировать успешность ваших FTP-операций.

ftp_nb_fput() и связанные функции

PHP предлагает несколько функций для загрузки файлов по FTP. Выбор подходящей зависит от того, есть ли у вас открытый файловый дескриптор или только путь, а также нужно ли неблокирующее поведение:

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

Все неблокирующие варианты используют один и тот же цикл FTP_MOREDATA / ftp_nb_continue().

Заключение

Функция ftp_nb_fput() загружает файл на FTP-сервер в неблокирующем режиме, позволяя скрипту продолжать выполнять другие операции во время передачи. Основной шаблон таков: начать загрузку, затем продолжать цикл с ftp_nb_continue(), пока возвращаемое значение равно FTP_MOREDATA, и проверять FTP_FAILED на каждом шаге. При правильном использовании это повышает отзывчивость кода для передачи файлов в ваших PHP-проектах.

Практика