ftp_set_option()

A função ftp_set_option() configura o comportamento em tempo de execução de uma conexão FTP já aberta em PHP. Ela permite ajustar como o cliente FTP se comporta — timeouts de conexão, endereçamento em modo passivo e se os downloads buscam automaticamente a posição ao retomar — sem precisar encerrar e restabelecer a conexão.

Esta página explica o que cada opção faz, quando utilizá-la e como definir as opções com segurança. Presume-se que você já tenha uma conexão aberta via ftp_connect() (ou ftp_ssl_connect()) e tenha se autenticado com ftp_login().

Sintaxe

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

A função retorna true em caso de sucesso, ou false se a opção não puder ser definida (por exemplo, quando $value tem o tipo errado para o $option escolhido).

Nota: No PHP 8.1+, o primeiro argumento é um objeto FTP\Connection. No PHP 8.0 e anteriores, é um resource retornado por ftp_connect(). O nome e o comportamento da função são os mesmos.

Uso básico

Abra uma conexão, autentique-se e defina a opção. A definição de opções geralmente ocorre logo após o login, antes de iniciar as transferências de arquivos, para que todas as transferências utilizem o novo comportamento.

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

Aqui nos conectamos com ftp_connect(), autenticamos com ftp_login(), reduzimos o timeout de rede para 30 segundos com ftp_set_option() e, por fim, encerramos a conexão com ftp_close().

Opções disponíveis

ftp_set_option() aceita as seguintes constantes de opção:

FTP_TIMEOUT_SEC e FTP_USEPASVADDRESS são as duas que você mais ajustará no código real: a primeira quando as transferências atingem o timeout, a segunda quando o modo passivo falha atrás de um firewall.

Você pode ler o valor atual de qualquer uma dessas opções com ftp_get_option().

Desativando o auto-seek

Um motivo comum para chamar ftp_set_option() é desativar o FTP_AUTOSEEK. Por padrão, ao retomar um download com um deslocamento diferente de zero, o arquivo local é buscado naquela posição. Se você quiser que cada download sobrescreva a partir do byte zero, desative-o:

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

Tratando falhas

ftp_set_option() retorna false (e emite um aviso) quando o valor não corresponde à opção — por exemplo, ao passar uma string onde um int é esperado. Verifique o valor de retorno para que uma opção silenciosamente ignorada não cause surpresas mais tarde:

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

Trabalhe sempre com uma conexão ativa: passar uma conexão fechada ou inválida gera um aviso em vez de um false limpo, portanto defina suas opções antes de chamar ftp_close().

Conclusão

ftp_set_option() ajusta o comportamento de uma conexão FTP aberta — principalmente seu timeout de rede e o tratamento de endereços em modo passivo atrás de NAT. Defina as opções imediatamente após ftp_login(), verifique o valor de retorno e use ftp_get_option() para confirmar o que está em vigor. Para o fluxo completo de FTP, consulte a visão geral do PHP FTP.

Prática