ftp_get_option()

What is ftp_get_option()?

The ftp_get_option() function is a PHP built-in function that retrieves a single runtime option of an open FTP connection. A runtime option is a configurable setting that controls how the FTP client behaves — for example, how long it waits before timing out, or whether it automatically resumes interrupted transfers. You read these settings with ftp_get_option() and change them with its counterpart ftp_set_option().

You typically reach for ftp_get_option() when you need to inspect the current configuration of a connection before deciding what to do next — for instance, logging the active timeout, or confirming that auto-resume is enabled before starting a large download.

The function takes two parameters:

1. ftp — the connection identifier returned by ftp_connect() (a FTP\Connection object in PHP 8.1+, or a resource in older versions).
2. option — the constant naming the option to retrieve (for example, FTP_TIMEOUT_SEC).

The function returns a mixed value depending on the queried option — an integer for FTP_TIMEOUT_SEC, or a boolean for the flag options. If the option name is unknown, PHP emits a warning and the function returns false.

Syntax of ftp_get_option()

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

Syntax of ftp_get_option()

mixed ftp_get_option ( FTP\Connection|resource $ftp_stream , int $option )

Both parameters are required. The $ftp_stream parameter is the connection identifier returned by ftp_connect() (or ftp_ssl_connect()), and $option is one of the predefined FTP_* constants described below.

Available options in ftp_get_option()

ftp_get_option() understands the following option constants. The return type differs per option, which matters when you check the result:

Note: FTP_USEPASVADDRESS is only meaningful in passive mode. FTP_LISTEN, which you may see in older notes, is not a valid option for ftp_get_option() and querying it produces a warning and false.

Usage of ftp_get_option()

To use the ftp_get_option() function, you first need to establish a connection to the FTP server using the ftp_connect() function. Here's an example:

Usage of ftp_get_option()

<?php

// Set up an FTP connection
$conn = ftp_connect('ftp.example.com');

// Login with your FTP credentials
ftp_login($conn, 'username', 'password');

// Retrieve the current timeout (in seconds)
$timeout = ftp_get_option($conn, FTP_TIMEOUT_SEC);
echo "Current timeout: {$timeout} seconds\n"; // Default: 90 seconds

// Check whether passive-address rewriting is enabled
$usePasv = ftp_get_option($conn, FTP_USEPASVADDRESS);
echo "Use PASV address: " . ($usePasv ? "yes" : "no") . "\n";

// Close the FTP connection
ftp_close($conn);

In this example, we connect with ftp_connect(), authenticate with ftp_login(), then read two options. The default FTP_TIMEOUT_SEC on a fresh connection is 90, so the first line prints Current timeout: 90 seconds. Finally we release the connection with ftp_close().

Error handling in ftp_get_option()

Because FTP_AUTOSEEK and FTP_USEPASVADDRESS legitimately return the boolean false, never test the result with a loose == — a disabled flag would look like a failure. Use the strict identity operator === to tell a real error apart from a valid false value:

Error handling in ftp_get_option()

<?php

$conn = ftp_connect('ftp.example.com');
ftp_login($conn, 'username', 'password');

$timeout = ftp_get_option($conn, FTP_TIMEOUT_SEC);

if ($timeout === false) {
    // The option name was invalid, or the connection is not usable
    echo "Failed to retrieve the option.\n";
} elseif ($timeout > 0) {
    echo "Timeout is set to {$timeout} seconds.\n";
} else {
    echo "No timeout is set.\n";
}

ftp_close($conn);

Here the strict === false check distinguishes a genuine retrieval failure from an option whose real value happens to be 0 or false. For boolean options such as FTP_USEPASVADDRESS, capture the result in a variable first and then compare with === before treating it as on or off.

Related functions

• ftp_set_option() — change a runtime option (the write counterpart of this function).
• ftp_connect() — open the connection these options apply to.
• ftp_pasv() — toggle passive mode, which interacts with FTP_USEPASVADDRESS.
• PHP FTP overview — all FTP functions at a glance.

Conclusion

The ftp_get_option() function lets you read the runtime configuration of an open FTP connection — most usefully the network timeout and the auto-resume and passive-address flags. Remember that some options return a boolean, so always check the result with === to avoid mistaking a valid false for an error.

Practice