ftp_set_option()

Функция ftp_set_option() настраивает поведение уже открытого FTP-соединения в PHP. С её помощью можно регулировать работу FTP-клиента — таймауты соединения, адресацию в пассивном режиме и автоматическое позиционирование при возобновлении загрузок — без разрыва и повторного установления соединения.

На этой странице описывается назначение каждой опции, когда её следует применять и как устанавливать параметры безопасно. Предполагается, что соединение уже открыто с помощью ftp_connect() (или ftp_ssl_connect()) и выполнена аутентификация через ftp_login().

Синтаксис

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

Функция возвращает true при успехе или false, если опцию не удалось установить (например, когда $value имеет неверный тип для выбранного $option).

Примечание: В PHP 8.1+ первый аргумент представляет собой объект FTP\Connection. В PHP 8.0 и более ранних версиях это resource, возвращаемый функцией ftp_connect(). Имя функции и её поведение при этом остаются прежними.

Базовое использование

Откройте соединение, выполните вход, затем установите опцию. Как правило, параметры задаются сразу после входа — до начала передачи файлов, чтобы новое поведение применялось ко всем передачам.

<?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);

Здесь мы устанавливаем соединение с помощью ftp_connect(), проходим аутентификацию через ftp_login(), снижаем сетевой таймаут до 30 секунд с помощью ftp_set_option() и наконец закрываем соединение функцией ftp_close().

Доступные опции

ftp_set_option() принимает следующие константы опций:

FTP_TIMEOUT_SEC и FTP_USEPASVADDRESS — две опции, которые чаще всего приходится изменять в реальном коде: первая — при таймаутах передачи, вторая — когда пассивный режим не работает за брандмауэром.

Текущее значение любой из этих опций можно прочитать с помощью ftp_get_option().

Отключение автоматического позиционирования

Распространённая причина вызова ftp_set_option() — отключение FTP_AUTOSEEK. По умолчанию при возобновлении загрузки с ненулевого смещения происходит позиционирование в локальном файле. Если требуется, чтобы каждая загрузка перезаписывала файл с нулевого байта, отключите эту опцию:

<?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);

Обработка ошибок

ftp_set_option() возвращает false (и выдаёт предупреждение), если значение не соответствует опции — например, при передаче строки вместо int. Проверяйте возвращаемое значение, чтобы молча проигнорированная опция не стала источником неожиданных проблем:

<?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);

Всегда работайте с активным соединением: передача закрытого или недействительного соединения вызовет предупреждение, а не корректное значение false, поэтому устанавливайте параметры до вызова ftp_close().

Заключение

ftp_set_option() настраивает поведение открытого FTP-соединения — в первую очередь сетевой таймаут и обработку адресов пассивного режима за NAT. Устанавливайте параметры сразу после ftp_login(), проверяйте возвращаемое значение и используйте ftp_get_option() для проверки текущих настроек. Полный обзор работы с FTP смотрите в разделе PHP FTP.

Практика