ftp_nb_fput()

Understanding the PHP Function ftp_nb_fput()

The ftp_nb_fput() function is a built-in PHP function that uploads a file to an FTP server using non-blocking mode. "Non-blocking" means the function returns control to your script before the transfer finishes, so you can run other code (update a progress bar, process another task) while the upload is still in progress. This article explains the parameters, return values, and a complete working pattern for using it in your PHP projects.

The blocking counterpart is ftp_fput(), which simply waits until the whole file is uploaded. Reach for ftp_nb_fput() only when you need to do work during the transfer.

What is ftp_nb_fput()?

The ftp_nb_fput() function uploads a file to an FTP server using non-blocking mode. It accepts four required parameters and one optional parameter:

1. ftp_stream: The connection identifier returned by ftp_connect().
2. remote_file: The path to the remote file on the FTP server.
3. handle: An open file pointer to the local file.
4. mode: The transfer mode, either FTP_ASCII or FTP_BINARY.
5. startpos (optional): The position in the remote file to start the upload from. Defaults to 0.

The function returns one of the following constants: FTP_SUCCESS (upload completed), FTP_MOREDATA (more data needs to be read), or FTP_FAILED (an error occurred).

Syntax of ftp_nb_fput()

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

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

The function takes four required parameters (ftp_stream, remote_file, handle, and mode) and one optional parameter (startpos). The ftp_stream parameter is the connection identifier returned by ftp_connect(). The remote_file parameter is the path to the remote file on the FTP server. The handle parameter is an open file pointer in the local file system. The mode parameter specifies the transfer mode, either FTP_ASCII or FTP_BINARY. The startpos parameter specifies the position in the remote file to start the upload from. By default, startpos is set to 0, which means the upload will start from the beginning of the file.

Usage of ftp_nb_fput()

To use the ftp_nb_fput() function, you first need to establish a connection to the FTP server using the ftp_connect() function and authenticate with ftp_login(). Here's a complete example:

<?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);

In this example, we establish a connection to the FTP server, log in with our credentials, and enable passive mode with ftp_pasv() to prevent common transfer issues behind firewalls. We open the local file for reading, then call ftp_nb_fput() to start the upload. The key detail is the while loop: as long as ftp_nb_fput() (or the follow-up calls) returns FTP_MOREDATA, we keep the transfer moving with ftp_nb_continue(). In a real application, each iteration of that loop is where you would do other work, since the transfer is non-blocking.

Error handling in ftp_nb_fput()

It's important to handle errors properly when using the ftp_nb_fput() function. The function returns specific constants rather than a boolean, so you must check for FTP_FAILED to detect errors. Here's an example of how to handle errors:

<?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);

By handling errors appropriately and checking the return constants of both ftp_nb_fput() and ftp_nb_continue(), you can ensure the success of your FTP operations.

ftp_nb_fput() vs. related functions

PHP offers several FTP upload functions. Choosing the right one depends on whether you have an open file handle or just a path, and whether you need non-blocking behavior:

• ftp_fput() — uploads from an open file handle, blocking until done.
• ftp_put() — uploads from a local file path, blocking until done.
• ftp_nb_put() — non-blocking upload from a local file path (same loop pattern as this function).
• ftp_nb_fput() — non-blocking upload from an open file handle (this function).

All of the non-blocking variants share the same FTP_MOREDATA / ftp_nb_continue() loop.

Conclusion

The ftp_nb_fput() function uploads a file to an FTP server in non-blocking mode, letting your script continue running other operations while the transfer is in progress. The essential pattern is: start the upload, then loop with ftp_nb_continue() while the return value is FTP_MOREDATA, and check for FTP_FAILED at every step. Used correctly, it improves the responsiveness of file-transfer code in your PHP projects.

Practice