PHP ftp_set_option() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
FTP

Definition

In PHP, ftp_set_option() changes a setting of an FTP connection, such as the timeout or whether file positions are detected automatically.

You pass the connection, one of the FTP_* option constants, and the new value. It is the setter partner of ftp_get_option().

Syntax

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

PHP
ftp_set_option($ftp, FTP_TIMEOUT_SEC, 120);
CallWhat it does
ftp_set_option($ftp, FTP_TIMEOUT_SEC, 120)Sets the network timeout to 120 seconds.
ftp_set_option($ftp, FTP_AUTOSEEK, false)Turns off automatic seeking when resuming transfers.
ftp_set_option($ftp, FTP_USEPASVADDRESS, false)Ignores the IP address sent by the server in passive mode, which helps behind some NAT setups.

The main options are FTP_TIMEOUT_SEC (an integer number of seconds greater than 0), FTP_AUTOSEEK (a boolean) and FTP_USEPASVADDRESS (a boolean). In PHP 8, passing an unknown option or a bad value throws a ValueError.

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

Parameters

ParameterDescription
ftpRequired. The FTP connection returned by ftp_connect() or ftp_ssl_connect().
optionRequired. One of the constants FTP_TIMEOUT_SEC, FTP_AUTOSEEK or FTP_USEPASVADDRESS.
valueRequired. The new value. It must be an int for FTP_TIMEOUT_SEC (above 0) and a bool for the other two options.

Return Value

Return ValueDescription
boolReturns true if the option was set. In PHP 8 an invalid option or value throws a ValueError.

PHP Examples

Example 1 — Set a Longer Timeout

Raise the timeout before a big transfer so the connection does not give up too soon.

PHP
<?php
$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'demo', 'secret');

if (ftp_set_option($ftp, FTP_TIMEOUT_SEC, 300)) {
    echo "Timeout is now ", ftp_get_option($ftp, FTP_TIMEOUT_SEC), " seconds", PHP_EOL;
}

ftp_close($ftp);

How It Works

  1. FTP_TIMEOUT_SEC is the constant for the network timeout setting.
  2. ftp_set_option() changes the timeout to 300 seconds.
  3. ftp_get_option() reads the value back to confirm it.
  4. A longer timeout helps with slow servers and large files.

Example 2 — Catch an Invalid Value

In PHP 8, a timeout of 0 or less throws a ValueError, so wrap the call in try and catch.

PHP
<?php
$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'demo', 'secret');

try {
    ftp_set_option($ftp, FTP_TIMEOUT_SEC, 0);
} catch (ValueError $e) {
    echo "Error: ", $e->getMessage(), PHP_EOL;
}

ftp_close($ftp);

How It Works

  1. A timeout of 0 does not make sense, so PHP rejects it.
  2. ftp_set_option() throws a ValueError instead of returning false.
  3. The catch block receives the error and prints its message.
  4. Use a positive number of seconds to avoid this problem.

Example 3 — Set Several Options Together

Apply a few options at once and print each current value to check them.

PHP
<?php
$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'demo', 'secret');

ftp_set_option($ftp, FTP_TIMEOUT_SEC, 60);
ftp_set_option($ftp, FTP_AUTOSEEK, false);
ftp_set_option($ftp, FTP_USEPASVADDRESS, false);

var_dump(ftp_get_option($ftp, FTP_TIMEOUT_SEC));
var_dump(ftp_get_option($ftp, FTP_AUTOSEEK));
var_dump(ftp_get_option($ftp, FTP_USEPASVADDRESS));

ftp_close($ftp);

How It Works

  1. FTP_TIMEOUT_SEC is set to 60 seconds with an integer value.
  2. FTP_AUTOSEEK and FTP_USEPASVADDRESS are turned off using false.
  3. ftp_get_option() reads each setting back from the connection.
  4. var_dump() shows both the type and the value, so you can see int(60) and bool(false).

Frequently Asked Questions

It changes a setting on an existing FTP connection, such as the timeout, auto seek, or the use of the passive mode address.
FTP_TIMEOUT_SEC, FTP_AUTOSEEK and FTP_USEPASVADDRESS. Each one has its own expected value type.
A whole number greater than 0, measured in seconds. A value of 0 or less throws a ValueError in PHP 8.
Set it to false when the server reports an internal IP address in passive mode, which can happen behind NAT or load balancers. PHP then uses the address you connected to instead.
Use ftp_get_option() with the same constant. It returns the current value for that option.

Next: ftp_site()

ftp_site() sends a SITE command to the FTP server. SITE commands are server specific extra.

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