ftp_nb_put()

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

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

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

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

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

1. ftp_stream: Идентификатор соединения, возвращаемый ftp_connect() (объект FTP\Connection в PHP 8.1+).
2. remote_file: Путь к удалённому файлу, куда будет загружен файл.
3. local_file: Путь к локальному файлу для чтения.
4. mode: Режим передачи: FTP_BINARY или FTP_ASCII (обязательный до PHP 7.3; необязательный и по умолчанию FTP_BINARY начиная с 7.3).
5. startpos (необязательный): Смещение в байтах в удалённом файле, с которого начинается запись; по умолчанию 0.

В отличие от блокирующей загрузки, ftp_nb_put() не возвращает простое true/false. Вместо этого она возвращает одну из трёх целочисленных констант:

Из-за этих возвращаемых значений ftp_nb_put() почти всегда используется совместно с ftp_nb_continue() в цикле, как показано ниже.

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

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

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

int ftp_nb_put ( FTP\Connection $ftp_stream , string $remote_file , string $local_file , int $mode [, int $startpos = 0 ] )

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

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

Для использования функции ftp_nb_put() сначала установите соединение с помощью ftp_connect() и выполните аутентификацию через ftp_login(). Затем начните загрузку и управляйте ею в цикле до завершения:

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

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

// Initiate an asynchronous FTP operation
$result = ftp_nb_put($conn, 'remote_file.txt', 'local_file.txt', FTP_BINARY);
if ($result === FTP_FAILED) {
    die('Upload failed.');
}

// 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);
}

if ($result === FTP_FINISHED) {
    echo "Upload completed successfully.\n";
}

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

В этом примере мы подключаемся к FTP-серверу, входим с учётными данными и начинаем загрузку с помощью ftp_nb_put(). Первый вызов возвращает FTP_MOREDATA, поэтому мы входим в цикл и многократно вызываем ftp_nb_continue() для отправки следующего блока данных — комментарий // Do something else указывает место, где можно обновлять индикатор прогресса или выполнять другую работу. После выхода из цикла проверяем FTP_FINISHED для подтверждения успеха, затем закрываем соединение с помощью ftp_close().

Примечание: Всегда вызывайте ftp_nb_continue() до тех пор, пока результат не перестанет быть FTP_MOREDATA. Если остановиться раньше, загрузка останется незавершённой на сервере.

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

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

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

<?php

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

if ($result === FTP_FAILED) {
    echo "Failed to upload file to remote server.\n";
}

while ($result === FTP_MOREDATA) {
    // Do something else while waiting for the FTP operation to complete
    $result = ftp_nb_continue($conn);
}

if ($result === FTP_FINISHED) {
    echo "Upload completed.\n";
}

ftp_close($conn);

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

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

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

Заключение

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

Примечание: функции ftp_nb_* считаются устаревшими в современном PHP. Для новых проектов рассмотрите использование cURL или асинхронной HTTP-библиотеки, например Guzzle, для лучшей производительности, безопасности и более широкой поддержки протоколов.

Практика