ftp_set_option()

The ftp_set_option() function configures runtime behavior for an already-open FTP connection in PHP. It lets you tune how the FTP client behaves — connection timeouts, passive-mode addressing, and whether downloads auto-seek when resuming — without tearing down and re-establishing the connection.

This page explains what each option does, when you would reach for it, and how to set the options safely. It assumes you already have a connection open via ftp_connect() (or ftp_ssl_connect()) and have logged in with ftp_login().

Syntax

ftp_set_option(FTP\Connection $ftp, int $option, mixed $value): bool

The function returns true on success, or false if the option could not be set (for example, when $value has the wrong type for the chosen $option).

Note: In PHP 8.1+ the first argument is an FTP\Connection object. On PHP 8.0 and earlier it is a resource returned by ftp_connect(). The function name and behavior are otherwise the same.

Basic usage

Open a connection, log in, then set the option. Setting options usually happens right after login, before you start transferring files, so that every transfer uses the new behavior.

<?php

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

if (!$ftp) {
    die('Could not connect to FTP server.');
}

// Authenticate
ftp_login($ftp, 'username', 'password');

// Abort any network operation that stalls for more than 30 seconds
ftp_set_option($ftp, FTP_TIMEOUT_SEC, 30);

// ... transfers happen here ...

ftp_close($ftp);

Here we connect with ftp_connect(), authenticate with ftp_login(), lower the network timeout to 30 seconds with ftp_set_option(), and finally close the connection with ftp_close().

Available options

ftp_set_option() accepts the following option constants:

FTP_TIMEOUT_SEC and FTP_USEPASVADDRESS are the two you will adjust most often in real code: the first when transfers time out, the second when passive mode fails behind a firewall.

You can read the current value of any of these back with ftp_get_option().

Disabling auto-seek

A common reason to call ftp_set_option() is to turn off FTP_AUTOSEEK. By default, resuming a download with a non-zero offset seeks the local file. If you want each download to overwrite from byte zero, disable it:

<?php

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

// Force full transfers instead of resuming from an offset
ftp_set_option($ftp, FTP_AUTOSEEK, false);

ftp_close($ftp);

Handling failures

ftp_set_option() returns false (and emits a warning) when the value does not match the option — for example, passing a string where an int is expected. Check the return value so a silently ignored option doesn't surprise you later:

<?php

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

if (!ftp_set_option($ftp, FTP_TIMEOUT_SEC, 30)) {
    echo "Failed to set the FTP timeout option.\n";
}

ftp_close($ftp);

Always work with a live connection: passing a closed or invalid connection produces a warning rather than a clean false, so set your options before calling ftp_close().

Conclusion

ftp_set_option() tunes how an open FTP connection behaves — most usefully its network timeout and its handling of passive-mode addresses behind NAT. Set options immediately after ftp_login(), check the return value, and use ftp_get_option() to confirm what is currently in effect. For the full FTP workflow, see the PHP FTP overview.

Practice