ftp_nb_get()

Understanding the PHP Function ftp_nb_get()

The ftp_nb_get() function downloads a file from an FTP server in non-blocking mode. Unlike its blocking counterpart ftp_get(), which halts your script until the entire file has been transferred, ftp_nb_get() returns control to your program almost immediately so you can do other work while the download runs in the background.

This page explains when to reach for the non-blocking variant, walks through every parameter and return value, and shows a complete working pattern with ftp_nb_continue().

When to use non-blocking mode

The "nb" in the name stands for non-blocking. Reach for ftp_nb_get() instead of ftp_get() when:

• You want to display progress or keep a UI responsive while a large file downloads.
• You need to interleave other work (logging, sending heartbeats, processing already-downloaded data) during the transfer.
• You want to enforce your own timeout or cancellation logic in the polling loop.

For a simple "download this file and wait", plain ftp_get() is simpler and is the better choice. The trade-off is that non-blocking mode requires you to drive the transfer yourself in a loop with ftp_nb_continue().

What is ftp_nb_get()?

The ftp_nb_get() function initiates an asynchronous file download. It requires four parameters:

1. ftp_stream: The connection identifier returned by ftp_connect().
2. local_file: The local file path where the downloaded file will be saved.
3. remote_file: The path to the remote file on the FTP server.
4. mode: The transfer mode, either FTP_ASCII or FTP_BINARY.

It also accepts an optional fifth parameter, resumepos, which specifies the position in the remote file to start the download from (defaults to 0).

The function returns one of three constants:

Because the function can return before the download is done, you almost always pair it with ftp_nb_continue() in a loop that runs while the result is FTP_MOREDATA.

Syntax of ftp_nb_get()

The syntax of the ftp_nb_get() function is as follows:

Syntax of ftp_nb_get()

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

The ftp_nb_get() function takes four required parameters (ftp_stream, local_file, remote_file, and mode) and one optional parameter (resumepos). The ftp_stream parameter is the connection identifier returned by ftp_connect(). The local_file parameter is the path to the local file where the downloaded file will be saved. The remote_file parameter is the path to the remote file on the FTP server. The mode parameter specifies the transfer mode, either FTP_ASCII or FTP_BINARY. The resumepos parameter specifies the position in the remote file to start the download from. By default, resumepos is set to 0, which means the download will start from the beginning of the file.

Usage of ftp_nb_get()

To use the ftp_nb_get() function, you first need to establish a connection to the FTP server using ftp_connect(). Here's an example:

Usage of 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);

In this example, we establish a connection to the FTP server using ftp_connect(). Then we log in using our FTP credentials using ftp_login(). We initiate an asynchronous FTP operation using ftp_nb_get(). We continue the operation using ftp_nb_continue() inside a loop that checks for FTP_MOREDATA, and finally close the FTP connection.

Resuming an interrupted download

The optional fifth parameter, resumepos, lets you continue a partially downloaded file instead of starting over. Pass the byte offset to resume from — typically the size of the file you already have on disk:

Resuming a download with 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);
}

This is especially useful for large files over unreliable connections, where you don't want to re-download data you already have.

Error handling in ftp_nb_get()

Always check the return value. ftp_nb_get() returns FTP_FAILED when it cannot start (or continue) the transfer, and ftp_nb_continue() can also return FTP_FAILED mid-stream. Handle both:

Error handling in 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);

By checking the connection, login, and the final state of the transfer separately, you can pinpoint exactly where an FTP operation went wrong.

Related functions

• ftp_get() — the blocking version that downloads a file and waits for it to finish.
• ftp_nb_continue() — continues a non-blocking transfer started by ftp_nb_get().
• ftp_nb_fget() — like ftp_nb_get(), but writes to an open file pointer instead of a path.
• ftp_connect() and ftp_login() — establish and authenticate the FTP session.
• ftp_close() — close the connection when you're done.

Conclusion

The ftp_nb_get() function downloads files from an FTP server in non-blocking mode, letting your script stay responsive while a transfer runs. Pair it with ftp_nb_continue() in a loop, check the return value against FTP_FINISHED and FTP_FAILED, and use resumepos to recover interrupted downloads.

Practice