ftp_nb_fget()

Understanding the PHP Function ftp_nb_fget()

The ftp_nb_fget() function is a built-in PHP function that retrieves a file from an FTP server and writes it to a local file using non-blocking mode. This article provides a comprehensive guide to using it in your PHP projects.

What is ftp_nb_fget()?

The ftp_nb_fget() function retrieves a remote file and writes it to an already-open local file pointer without blocking the script. Non-blocking means the call returns immediately instead of pausing until the whole file has been transferred, so your script can keep doing other work while the download runs in the background.

It takes four parameters (three required, one optional):

The function returns one of three constants:

• FTP_FINISHED — the transfer completed successfully.
• FTP_MOREDATA — the transfer is still in progress; call ftp_nb_continue() to keep going.
• FTP_FAILED — an error occurred.

Blocking vs. non-blocking: the blocking equivalent is ftp_fget(), which returns only once the file is fully transferred. Reach for ftp_nb_fget() when you want to show progress, run other work, or transfer several files in parallel-ish fashion.

Syntax of ftp_nb_fget()

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

Syntax of ftp_nb_fget()

int ftp_nb_fget ( resource $ftp_stream , resource $handle , string $remote_file , int $mode [, int $resumepos = 0 ] )

Use FTP_BINARY for any non-text file (images, archives, executables) so bytes are copied verbatim; FTP_ASCII translates line endings and should only be used for plain-text files. The resumepos parameter is handy for continuing a partially downloaded file: pass the size of the local file so the transfer picks up where it left off instead of starting over.

Usage of ftp_nb_fget()

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

Usage of ftp_nb_fget()

<?php

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

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

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

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

// Check final result
if ($result === FTP_FINISHED) {
    echo "Download completed successfully.";
} else {
    echo "Download failed.";
}

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

In this example, we establish a connection to the FTP server using ftp_connect(). Then we log in using ftp_login(). We open a file for writing using fopen() and initiate an asynchronous FTP operation using ftp_nb_fget(). We continue the operation using ftp_nb_continue() inside a while loop that checks for the FTP_MOREDATA constant. Finally, we check the result and close the file and FTP connection.

Error handling in ftp_nb_fget()

It's important to handle errors properly when using the ftp_nb_fget() function. The function and ftp_nb_continue() return state constants rather than simple booleans. Here's an example of how to handle errors and check transfer states:

Error handling in ftp_nb_fget()

<?php

// Assuming $conn is an established FTP connection
$handle = fopen('local_file.txt', 'w');
$result = ftp_nb_fget($conn, $handle, 'remote_file.txt', FTP_BINARY);

if ($result === FTP_FAILED) {
    echo "Failed to start download.\n";
} else {
    while ($result === FTP_MOREDATA) {
        $result = ftp_nb_continue($conn);
    }

    if ($result === FTP_FINISHED) {
        echo "Download completed successfully.\n";
    } else {
        echo "Download failed during transfer.\n";
    }
}

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

Related functions

• ftp_fget() — the blocking version that downloads to an open file pointer.
• ftp_nb_get() — non-blocking download straight to a local path (no fopen() needed).
• ftp_nb_continue() — drives the transfer started by ftp_nb_fget().
• ftp_nb_fput() — the non-blocking counterpart for uploading.
• ftp_connect() and ftp_login() — open and authenticate the connection.

Conclusion

The ftp_nb_fget() function retrieves files from an FTP server in non-blocking mode, letting your script continue with other work while the download proceeds. Always loop on ftp_nb_continue() while the state is FTP_MOREDATA, and check the final constant (FTP_FINISHED or FTP_FAILED) before treating the file as complete.

Note: The FTP extension is considered legacy. For modern applications, prefer SFTP (via the ssh2 extension or phpseclib) or asynchronous HTTP clients for better security and performance.

Practice