ftp_get_option()

O que é ftp_get_option()?

A função ftp_get_option() é uma função embutida do PHP que recupera uma única opção de tempo de execução de uma conexão FTP aberta. Uma opção de tempo de execução é uma configuração ajustável que controla o comportamento do cliente FTP — por exemplo, quanto tempo ele aguarda antes de expirar, ou se retoma automaticamente transferências interrompidas. Você lê essas configurações com ftp_get_option() e as altera com seu equivalente ftp_set_option().

Você normalmente usa ftp_get_option() quando precisa inspecionar a configuração atual de uma conexão antes de decidir o que fazer a seguir — por exemplo, registrar o timeout ativo ou confirmar que o auto-retomar está habilitado antes de iniciar um download grande.

A função recebe dois parâmetros:

1. ftp — o identificador de conexão retornado por ftp_connect() (um objeto FTP\Connection no PHP 8.1+, ou um resource em versões mais antigas).
2. option — a constante que nomeia a opção a recuperar (por exemplo, FTP_TIMEOUT_SEC).

A função retorna um valor mixed dependendo da opção consultada — um inteiro para FTP_TIMEOUT_SEC, ou um boolean para as opções de flag. Se o nome da opção for desconhecido, o PHP emite um aviso e a função retorna false.

Sintaxe de ftp_get_option()

A sintaxe da função ftp_get_option() é a seguinte:

Sintaxe de ftp_get_option()

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

Ambos os parâmetros são obrigatórios. O parâmetro $ftp_stream é o identificador de conexão retornado por ftp_connect() (ou ftp_ssl_connect()), e $option é uma das constantes FTP_* predefinidas descritas abaixo.

Opções disponíveis em ftp_get_option()

ftp_get_option() reconhece as seguintes constantes de opção. O tipo de retorno varia por opção, o que importa ao verificar o resultado:

Nota: FTP_USEPASVADDRESS só é relevante no modo passivo. FTP_LISTEN, que pode aparecer em notas mais antigas, não é uma opção válida para ftp_get_option() e consultá-la produz um aviso e false.

Uso de ftp_get_option()

Para usar a função ftp_get_option(), primeiro você precisa estabelecer uma conexão com o servidor FTP usando a função ftp_connect(). Veja um exemplo:

Uso de 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);

Neste exemplo, nos conectamos com ftp_connect(), autenticamos com ftp_login(), e depois lemos duas opções. O valor padrão de FTP_TIMEOUT_SEC em uma nova conexão é 90, portanto a primeira linha imprime Current timeout: 90 seconds. Por fim, liberamos a conexão com ftp_close().

Tratamento de erros em ftp_get_option()

Como FTP_AUTOSEEK e FTP_USEPASVADDRESS legitimamente retornam o boolean false, nunca teste o resultado com == solto — uma flag desativada pareceria uma falha. Use o operador de identidade estrito === para distinguir um erro real de um valor false válido:

Tratamento de erros em 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);

Aqui a verificação estrita === false distingue uma falha genuína de recuperação de uma opção cujo valor real é 0 ou false. Para opções boolean como FTP_USEPASVADDRESS, capture o resultado em uma variável primeiro e depois compare com === antes de tratá-la como ativada ou desativada.

Funções relacionadas

• ftp_set_option() — altera uma opção de tempo de execução (o equivalente de escrita desta função).
• ftp_connect() — abre a conexão à qual essas opções se aplicam.
• ftp_pasv() — alterna o modo passivo, que interage com FTP_USEPASVADDRESS.
• Visão geral do FTP em PHP — todas as funções FTP de relance.

Conclusão

A função ftp_get_option() permite ler a configuração de tempo de execução de uma conexão FTP aberta — mais útil para o timeout de rede e as flags de auto-retomar e endereço passivo. Lembre-se de que algumas opções retornam um boolean, portanto sempre verifique o resultado com === para evitar confundir um false válido com um erro.

Prática