ftp_nb_put()

Understanding the PHP Function ftp_nb_put()

The ftp_nb_put() function is a built-in PHP function that uploads a file to an FTP server using non-blocking mode. "Non-blocking" means the call returns immediately after starting the transfer instead of waiting for it to finish, so your script can keep doing other work while bytes travel over the wire. This guide covers its parameters, syntax, usage, and error handling so you can integrate it effectively into your PHP projects.

The companion to this function is ftp_put(), which uploads in blocking mode (the script pauses until the upload completes). Reach for ftp_nb_put() when you want to upload a large file while showing progress, processing other tasks, or avoiding a long, frozen request.

What is ftp_nb_put()?

The ftp_nb_put() function uploads a file to an FTP server without halting script execution. It accepts these parameters:

1. ftp_stream: The connection identifier returned by ftp_connect() (an FTP\Connection object in PHP 8.1+).
2. remote_file: The remote file path where the file will be uploaded.
3. local_file: The local file path to read from.
4. mode: The transfer mode, either FTP_BINARY or FTP_ASCII (required before PHP 7.3; optional and defaulting to FTP_BINARY from 7.3 onward).
5. startpos (optional): The byte offset in the remote file at which to start writing; defaults to 0.

Unlike a blocking upload, ftp_nb_put() does not return a simple true/false. Instead it returns one of three integer constants:

Because of these return values, ftp_nb_put() is almost always used together with ftp_nb_continue() in a loop, as shown below.

Syntax of ftp_nb_put()

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

Syntax of ftp_nb_put()

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

The ftp_nb_put() function takes three required parameters (ftp_stream, remote_file, and local_file) and one optional parameter (startpos). The mode parameter is required and specifies the transfer mode: FTP_BINARY is recommended for most files (images, archives, executables) to prevent line-ending corruption, while FTP_ASCII is used for plain text files (though FTP_BINARY is generally safer for all file types). 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_put()

To use the ftp_nb_put() function, you first establish a connection with ftp_connect() and authenticate with ftp_login(). You then start the upload and drive it forward in a loop until it finishes:

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

In this example, we connect to the FTP server, log in with our credentials, and start the upload with ftp_nb_put(). The first call returns FTP_MOREDATA, so we enter a loop and repeatedly call ftp_nb_continue() to send the next chunk — the // Do something else comment is where you would update a progress bar or handle other work. When the loop exits we check for FTP_FINISHED to confirm success, then close the connection with ftp_close().

Note: Always call ftp_nb_continue() until the result is no longer FTP_MOREDATA. If you stop early, the upload is left incomplete on the server.

Error handling in ftp_nb_put()

It's important to handle errors properly when using the ftp_nb_put() function. If the function returns FTP_FAILED, it means that the upload was unsuccessful. Here's an example of how to handle errors:

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

By handling errors appropriately and checking the return value of the function, you can ensure the success of your FTP operations using the ftp_nb_put() function.

Related functions

• ftp_put() — upload a file in blocking mode (simpler, but pauses the script).
• ftp_nb_continue() — continue a non-blocking transfer started by ftp_nb_put().
• ftp_nb_fput() — non-blocking upload from an already-open file handle instead of a path.
• ftp_nb_get() — the download counterpart of ftp_nb_put().

Conclusion

The ftp_nb_put() function uploads files to an FTP server in non-blocking mode, letting your script continue with other work while the transfer runs in the background. The key is to start the upload, loop over ftp_nb_continue() while the status is FTP_MOREDATA, and confirm FTP_FINISHED (handling FTP_FAILED) before closing the connection. With proper usage and error handling, it is a valuable tool for responsive file transfers in your PHP projects.

Note: The ftp_nb_* functions are considered legacy in modern PHP. For new projects, consider using cURL or an asynchronous HTTP library like Guzzle for better performance, security, and broader protocol support.

Practice