ftp_get_option()

Что такое ftp_get_option()?

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

Функция ftp_get_option() обычно используется, когда нужно проверить текущую конфигурацию соединения перед принятием дальнейших решений — например, записать в лог активное значение тайм-аута или убедиться, что автовозобновление включено перед началом загрузки большого файла.

Функция принимает два параметра:

1. ftp — идентификатор соединения, возвращаемый ftp_connect() (объект FTP\Connection в PHP 8.1+, или ресурс в старых версиях).
2. option — константа, указывающая имя извлекаемого параметра (например, FTP_TIMEOUT_SEC).

Функция возвращает значение типа mixed в зависимости от запрашиваемого параметра: целое число для FTP_TIMEOUT_SEC или boolean для флаговых параметров. Если имя параметра неизвестно, PHP выдаёт предупреждение и функция возвращает false.

Синтаксис ftp_get_option()

Синтаксис функции ftp_get_option() выглядит следующим образом:

Синтаксис ftp_get_option()

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

Оба параметра обязательны. Параметр $ftp_stream — это идентификатор соединения, возвращаемый ftp_connect() (или ftp_ssl_connect()), а $option — одна из предопределённых констант FTP_*, описанных ниже.

Доступные параметры в ftp_get_option()

Функция ftp_get_option() поддерживает следующие константы параметров. Тип возвращаемого значения различается в зависимости от параметра, что важно учитывать при проверке результата:

Примечание: FTP_USEPASVADDRESS имеет смысл только в пассивном режиме. FTP_LISTEN, который можно встретить в старых материалах, не является допустимым параметром для ftp_get_option() — его запрос вызывает предупреждение и возвращает false.

Использование ftp_get_option()

Чтобы использовать функцию ftp_get_option(), необходимо сначала установить соединение с FTP-сервером с помощью функции ftp_connect(). Вот пример:

Использование 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);

В этом примере мы устанавливаем соединение с помощью ftp_connect(), выполняем аутентификацию через ftp_login(), затем читаем два параметра. Значение FTP_TIMEOUT_SEC по умолчанию для нового соединения равно 90, поэтому первая строка выведет Current timeout: 90 seconds. В конце освобождаем соединение с помощью ftp_close().

Обработка ошибок в ftp_get_option()

Поскольку FTP_AUTOSEEK и FTP_USEPASVADDRESS могут законно возвращать boolean false, никогда не проверяйте результат с помощью нестрогого == — отключённый флаг выглядел бы как ошибка. Используйте строгий оператор идентичности ===, чтобы отличить реальную ошибку от допустимого значения false:

Обработка ошибок в 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);

Здесь строгая проверка === false позволяет отличить реальную ошибку извлечения от параметра, чьё настоящее значение равно 0 или false. Для boolean-параметров, таких как FTP_USEPASVADDRESS, сначала сохраните результат в переменную, а затем сравнивайте с ===, прежде чем интерпретировать его как включённый или выключенный.

Связанные функции

• ftp_set_option() — изменить параметр времени выполнения (аналог этой функции для записи).
• ftp_connect() — открыть соединение, к которому применяются эти параметры.
• ftp_pasv() — переключить пассивный режим, который взаимодействует с FTP_USEPASVADDRESS.
• Обзор PHP FTP — все FTP-функции в одном месте.

Заключение

Функция ftp_get_option() позволяет читать конфигурацию времени выполнения открытого FTP-соединения — прежде всего тайм-аут сети, а также флаги автовозобновления и пассивного адреса. Помните, что некоторые параметры возвращают boolean, поэтому всегда проверяйте результат с помощью ===, чтобы не спутать допустимое значение false с ошибкой.

Практика