ftp_size()

The PHP ftp_size() Function

ftp_size() is a built-in PHP function that asks an FTP server for the size, in bytes, of a single remote file. You use it when you need to know how big a file is without downloading it — for example, to show a progress bar, decide whether a file changed since the last sync, skip empty files, or verify that an upload completed at the expected size.

This page covers the signature, a complete working example, the one gotcha that trips up almost everyone (passive mode), and how to handle the special return values.

Syntax

ftp_size(FTP\Connection $ftp, string $filename): int

Return value: the file size in bytes as an integer on success, or -1 on error.

Important: ftp_size() returns the integer -1 on failure — it does not return false. This is different from most other FTP functions, so always compare against -1, not false.

Before PHP 8.1 the $ftp argument was a resource; from PHP 8.1 onward it is an FTP\Connection object. Your code does not change — only the underlying type does.

Basic Usage

To call ftp_size() you first open a connection with ftp_connect() and authenticate with ftp_login():

<?php

// Open a connection to the FTP server
$conn = ftp_connect('ftp.example.com');

// Log in with your credentials
ftp_login($conn, 'username', 'password');

// Turn on passive mode (see the note below — this is almost always required)
ftp_pasv($conn, true);

// Ask the server how big the file is
$size = ftp_size($conn, '/public_html/index.php');

if ($size !== -1) {
    echo "The file is {$size} bytes.";
} else {
    echo "Could not determine the file size.";
}

// Always close the connection when you are done
ftp_close($conn);

Passive Mode: the Most Common Pitfall

If ftp_size() keeps returning -1 even though the file clearly exists, the cause is usually active vs. passive mode, not a typo in the path. Behind a firewall or NAT (which describes most servers today), the FTP server cannot open a data channel back to your client, so the underlying SIZE command stalls.

Call ftp_pasv() after logging in to switch to passive mode, where your client initiates every connection:

<?php
ftp_login($conn, 'username', 'password');
ftp_pasv($conn, true); // do this before ftp_size(), ftp_get(), ftp_nlist(), etc.

Transfer Mode Affects the Result

The size an FTP server reports can depend on the current transfer mode. In ASCII mode some servers translate line endings, so the reported size may not match the byte count you get in binary mode. For accurate byte-for-byte sizes, make sure you are in binary mode (FTP_BINARY), which is the default for size queries on most servers and the mode you almost always want for non-text files.

Robust Error Handling

Because ftp_size() signals failure with -1, a reliable wrapper checks for that specific value and warns when the size is unknown:

<?php

function remoteFileSize($conn, string $path): ?int
{
    $size = ftp_size($conn, $path);

    if ($size === -1) {
        // The file is missing, the path is wrong, or the SIZE command failed.
        return null;
    }

    return $size;
}

$size = remoteFileSize($conn, '/public_html/index.php');

echo $size === null
    ? "File not found or size unavailable.\n"
    : "Size: {$size} bytes\n";

Using null for the failure case keeps -1 from leaking into later arithmetic (where it would silently corrupt totals).

Listing Sizes for Many Files

ftp_size() works on one path at a time. To report sizes for a whole directory, combine it with ftp_nlist(), which returns an array of file names:

<?php

$files = ftp_nlist($conn, '/public_html');

if ($files !== false) {
    foreach ($files as $file) {
        $size = ftp_size($conn, $file);
        $label = $size === -1 ? 'directory or unreadable' : "{$size} bytes";
        echo "{$file}: {$label}\n";
    }
}

Note that ftp_size() returns -1 for directories, which is a handy way to tell files and folders apart in a listing.

Related Functions

• ftp_connect() — open the connection you pass to ftp_size().
• ftp_login() — authenticate before any size query.
• ftp_pasv() — enable passive mode so ftp_size() actually succeeds.
• ftp_nlist() — list a directory to size many files in a loop.
• ftp_get() — download a file once you know its size.
• ftp_close() — close the connection when finished.
• PHP FTP overview — all the FTP functions in one place.

Conclusion

ftp_size() is the quickest way to learn a remote file's byte size without transferring it. Remember the two rules that make it reliable: enable passive mode with ftp_pasv() after login, and test the result against -1 (not false) to detect failures and directories.

Practice