PHP ftp_nb_get() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
FTP

Definition

In PHP, ftp_nb_get() starts a non-blocking download of a remote file and saves it to a local file name that you choose.

Unlike ftp_get(), which waits until the whole file arrives, ftp_nb_get() returns after the first chunk. You then call ftp_nb_continue() in a loop to get the rest. That makes it a good choice for large files or progress messages.

Syntax

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

PHP
$status = ftp_nb_get($ftp, 'local.zip', 'remote.zip', FTP_BINARY);
CallWhat it does
ftp_nb_get($ftp, 'local.zip', 'remote.zip')Starts downloading remote.zip into local.zip using binary mode.
ftp_nb_get($ftp, 'notes.txt', 'notes.txt', FTP_ASCII)Downloads a text file in ASCII mode.
ftp_nb_get($ftp, 'big.iso', 'big.iso', FTP_BINARY, 4096)Resumes the download from byte 4096 of the remote file.

It returns FTP_MOREDATA, FTP_FINISHED or FTP_FAILED. When you get FTP_MOREDATA, call ftp_nb_continue() until the transfer ends. PHP opens and writes the local file for you.

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

Parameters

ParameterDescription
ftpRequired. The FTP\Connection object returned by ftp_connect() or ftp_ssl_connect().
local_filenameRequired. The path of the local file where the data is saved. An existing file is overwritten.
remote_filenameRequired. The path of the file on the FTP server.
modeOptional. The transfer mode, FTP_ASCII or FTP_BINARY. The default is FTP_BINARY.
offsetOptional. The position in the remote file where the download starts. The default is 0.

Return Value

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

PHP Examples

Example 1 — Download a File in Chunks

Start a non-blocking download and loop until the transfer is finished.

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

$status = ftp_nb_get($ftp, 'report.pdf', 'docs/report.pdf', FTP_BINARY);

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

if ($status === FTP_FINISHED) {
    echo "report.pdf downloaded", PHP_EOL;
}

ftp_close($ftp);

How It Works

  1. ftp_nb_get() begins saving docs/report. pdf as report.pdf in the current folder.
  2. The status FTP_MOREDATA tells you that more data is waiting.
  3. The while loop calls ftp_nb_continue() until the status changes.
  4. FTP_FINISHED confirms that the download succeeded.

Example 2 — Check for Failure

When the remote file is missing or the local folder is not writable, you get FTP_FAILED. Always test for it.

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

$status = @ftp_nb_get($ftp, 'copy.txt', 'no-such-file.txt', FTP_ASCII);

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

if ($status === FTP_FAILED) {
    echo "Download failed", PHP_EOL;
} else {
    echo "Download complete", PHP_EOL;
}

ftp_close($ftp);

How It Works

  1. The remote file does not exist, so the server refuses the request.
  2. ftp_nb_get() returns FTP_FAILED straight away.
  3. The while loop is skipped because the status is not FTP_MOREDATA.
  4. The if statement reports the problem to the user.

Example 3 — Download Several Files One After Another

Only one non-blocking transfer can run at a time, so finish each file before starting the next.

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

$files = ['a.txt', 'b.txt', 'c.txt'];

foreach ($files as $file) {
    $status = ftp_nb_get($ftp, $file, $file, FTP_ASCII);

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

    echo $file, ': ', $status === FTP_FINISHED ? 'ok' : 'failed', PHP_EOL;
}

ftp_close($ftp);

How It Works

  1. The foreach loop picks one file name at a time.
  2. Each file is fully downloaded by the inner while loop before the next begins.
  3. The ternary prints ok or failed based on the final status.
  4. A failure on one file does not stop the others.

Frequently Asked Questions

It starts a non-blocking download of a remote file into a local file. You finish it by calling ftp_nb_continue() until the transfer ends.
ftp_get() blocks until the file is fully downloaded. ftp_nb_get() returns after the first chunk so your script can do other things in between.
It means the download is not finished yet. Call ftp_nb_continue() again, and repeat until you get FTP_FINISHED or FTP_FAILED.
Yes, a file with the same local name is overwritten when the transfer starts without an offset.
Usually yes. Calling ftp_pasv($ftp, true) after login helps when you are behind a firewall or a NAT router.

Next: ftp_nb_put()

ftp_nb_put() starts a non-blocking upload of a local file to an FTP server. The local file.

ftp_nb_put() 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