PHP ftp_nb_put() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
FTP

Definition

In PHP, ftp_nb_put() starts a non-blocking upload of a local file to an FTP server. The local file is given by its name, so you do not need to open it yourself.

It is the non-blocking version of ftp_put(). It sends the first chunk and returns, then you call ftp_nb_continue() until the upload ends. Your script stays free to do other work or show progress during large uploads.

Syntax

Call ftp_nb_put() with the values you need. Start with this line.

PHP
$status = ftp_nb_put($ftp, 'remote.zip', 'local.zip', FTP_BINARY);
CallWhat it does
ftp_nb_put($ftp, 'remote.zip', 'local.zip')Starts uploading local.zip as remote.zip in binary mode.
ftp_nb_put($ftp, 'notes.txt', 'notes.txt', FTP_ASCII)Uploads a text file using ASCII mode.
ftp_nb_put($ftp, 'big.iso', 'big.iso', FTP_BINARY, 8192)Resumes an upload starting at byte 8192 of the remote file.

Mind the argument order: the remote name comes first, then the local name. It returns FTP_MOREDATA, FTP_FINISHED or FTP_FAILED, so keep calling ftp_nb_continue() while the result is FTP_MOREDATA.

Library declarations
PHP
ftp_nb_put(FTP\Connection $ftp, string $remote_filename, string $local_filename, int $mode = FTP_BINARY, int $offset = 0): int

Parameters

ParameterDescription
ftpRequired. The FTP\Connection object returned by ftp_connect() or ftp_ssl_connect().
remote_filenameRequired. The path where the file is stored on the FTP server.
local_filenameRequired. The path of the local file that you want to upload.
modeOptional. The transfer mode, FTP_ASCII or FTP_BINARY. The default is FTP_BINARY.
offsetOptional. The position in the remote file where the upload starts. The default is 0.

Return Value

Return ValueDescription
intFTP_MOREDATA if the upload is still running, FTP_FINISHED when it is done, or FTP_FAILED on error.

PHP Examples

Example 1 — Upload a File in Chunks

Start a non-blocking upload and loop until the server has received everything.

PHP
<?php
$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'username', 'password');
ftp_pasv($ftp, true);

$status = ftp_nb_put($ftp, 'uploads/photo.jpg', 'photo.jpg', FTP_BINARY);

while ($status === FTP_MOREDATA) {
    $status = ftp_nb_continue($ftp);
}

echo $status === FTP_FINISHED ? "Upload complete" : "Upload failed", PHP_EOL;

ftp_close($ftp);

How It Works

  1. The remote path comes first, and the local file name comes second.
  2. ftp_nb_put() sends the first chunk and returns FTP_MOREDATA.
  3. The loop keeps calling ftp_nb_continue() until the upload ends.
  4. The ternary prints a message based on the final status.

Example 2 — Check That the Local File Exists

ftp_nb_put() cannot upload a file that is not there. Check first so your script fails gracefully.

PHP
<?php
$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'username', 'password');
ftp_pasv($ftp, true);

$local = 'missing.zip';

if (!is_readable($local)) {
    echo "Local file not found: {$local}", PHP_EOL;
    ftp_close($ftp);
    exit(1);
}

$status = ftp_nb_put($ftp, 'missing.zip', $local, FTP_BINARY);

while ($status === FTP_MOREDATA) {
    $status = ftp_nb_continue($ftp);
}

How It Works

  1. is_readable() confirms that the local file exists and PHP can read it.
  2. If the file is missing, the script prints a message and stops.
  3. No upload is attempted, so no broken file is created on the server.
  4. The upload code only runs when the file is available.

Example 3 — Upload With a Progress Message

Use the loop to print simple progress while a large file is being uploaded.

PHP
<?php
$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'username', 'password');
ftp_pasv($ftp, true);

$status = ftp_nb_put($ftp, 'backup.zip', 'backup.zip', FTP_BINARY);
$loops = 0;

while ($status === FTP_MOREDATA) {
    $loops++;
    if ($loops % 50 === 0) {
        echo "Uploading... ({$loops})", PHP_EOL;
    }
    $status = ftp_nb_continue($ftp);
}

if ($status === FTP_FINISHED) {
    echo "backup.zip uploaded", PHP_EOL;
} else {
    echo "Upload failed", PHP_EOL;
}

ftp_close($ftp);

How It Works

  1. $loops counts how many chunks have been handled.
  2. Every 50 loops the script prints a short progress line.
  3. ftp_nb_continue() sends the next chunk on each pass.
  4. A final if statement confirms success or reports failure.

Frequently Asked Questions

It starts a non-blocking upload of a local file to an FTP server. You finish the upload by calling ftp_nb_continue() in a loop.
ftp_put() waits until the whole file is uploaded. ftp_nb_put() returns after the first chunk so your script can keep working.
The remote file name comes first and the local file name comes second: ftp_nb_put($ftp, $remote, $local).
FTP_MOREDATA means the upload is still running. FTP_FINISHED means it completed. FTP_FAILED means an error stopped the upload.
Yes. Pass the number of bytes already on the server as the offset. You can get that number with ftp_size().

Next: ftp_nlist()

ftp_nlist() returns a simple list of file and folder names inside a directory on an FTP se.

ftp_nlist() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful