ftp_get()

O que é ftp_get()?

ftp_get() é uma função embutida do PHP que baixa um arquivo de um servidor FTP e o grava em um arquivo local na sua máquina. É a contraparte de leitura de ftp_put(), que faz upload. Use-a sempre que precisar obter um arquivo (um backup, um log, um relatório) de um servidor remoto via FTP.

Esta página cobre o que ftp_get() faz, seus parâmetros e valor de retorno, um fluxo completo de uso (conectar → fazer login → baixar → fechar), como lidar com falhas e os erros comuns que pegam as pessoas de surpresa (modo de transferência, modo passivo e retomada de downloads parciais).

Parâmetros

ftp_get() recebe cinco parâmetros — três obrigatórios e dois opcionais:

Valor de retorno

A função retorna um boolean: true em caso de sucesso, false em caso de falha. Sempre verifique — um download com falha não lança uma exceção por padrão.

FTP_BINARY vs FTP_ASCII

FTP_BINARY transfere o arquivo byte a byte e é correto para quase tudo: imagens, PDFs, arquivos compactados, executáveis e até a maioria dos arquivos de texto. FTP_ASCII realiza conversão automática de terminação de linha entre as convenções do servidor e do cliente, portanto, use-o somente para arquivos de texto simples onde você realmente deseja essa conversão. Usar FTP_ASCII em um arquivo binário irá corrompê-lo, então, na dúvida, escolha FTP_BINARY.

Sintaxe de ftp_get()

bool ftp_get ( resource $ftp_stream , string $local_file , string $remote_file [, int $mode = FTP_BINARY [, int $resumepos = 0 ]] )

Nota: No PHP 8.1+, o tipo resource para conexões FTP foi substituído por um objeto Ftp\Connection, e o parâmetro mode tornou-se opcional (com padrão FTP_BINARY). A assinatura legada com resource acima é mantida para compatibilidade retroativa — seu código não precisa ser alterado.

Uso de ftp_get()

Para usar ftp_get(), primeiro estabeleça uma conexão com ftp_connect() e autentique-se com ftp_login(). Aqui está o fluxo completo:

Baixando um arquivo com ftp_get()

<?php
// 1. Set up an FTP connection
$conn = ftp_connect('ftp.example.com');
if (!$conn) {
    die("Could not connect to FTP server.\n");
}

// 2. Log in with your FTP credentials
if (!ftp_login($conn, 'username', 'password')) {
    ftp_close($conn);
    die("Login failed.\n");
}

// 3. Switch to passive mode (required behind most firewalls/NAT)
ftp_pasv($conn, true);

// 4. Download the remote file into a local path
if (ftp_get($conn, '/local/directory/local_file.txt', 'remote_file.txt', FTP_BINARY)) {
    echo "File retrieved successfully.\n";
} else {
    echo "Failed to retrieve the file.\n";
}

// 5. Close the FTP connection
ftp_close($conn);

Os passos são sempre os mesmos: conectar, fazer login, opcionalmente ativar o modo passivo, baixar e fechar. O modo passivo (ftp_pasv()) é ativado aqui porque a maioria dos clientes está atrás de um firewall ou NAT, e as transferências em modo ativo poderiam travar ou falhar. Observe que você deve chamar ftp_pasv() após fazer login.

Tratamento de erros em ftp_get()

ftp_get() retorna false em caso de falha em vez de lançar uma exceção, portanto, verifique o valor de retorno explicitamente. Causas comuns são um arquivo remoto ausente, permissões insuficientes ou um caminho local que não pode ser escrito. O PHP também emite um aviso, que você pode capturar para registro em log:

Capturando o motivo da falha de um download

<?php
// $conn is an open, logged-in FTP connection
$ok = @ftp_get($conn, '/local/directory/local_file.txt', 'remote_file.txt', FTP_BINARY);

if ($ok === false) {
    $error = error_get_last();
    echo "Failed to retrieve the file: " . ($error['message'] ?? 'unknown error') . "\n";
} else {
    echo "File retrieved successfully.\n";
}

O @ suprime o aviso bruto do PHP para que você possa formatar sua própria mensagem, enquanto error_get_last() ainda fornece o detalhe subjacente para um log.

Retomando um download interrompido

O parâmetro opcional resumepos permite continuar um download que foi interrompido, em vez de reiniciar do zero. Passe o tamanho atual do arquivo local parcialmente baixado como o offset em bytes:

Retomando com resumepos

<?php
// $conn is an open, logged-in FTP connection
$local = '/local/directory/big_archive.zip';

// Continue from however many bytes we already have locally
$offset = file_exists($local) ? filesize($local) : 0;

if (ftp_get($conn, $local, 'big_archive.zip', FTP_BINARY, $offset)) {
    echo "Download complete.\n";
} else {
    echo "Resume failed.\n";
}

A retomada só funciona de forma confiável com FTP_BINARY e em servidores que suportam o comando REST. Para transferências grandes, você também pode usar a variante não bloqueante ftp_nb_get(), que faz o download em segundo plano para que seu script possa realizar outros trabalhos.

Funções relacionadas

• ftp_put() — faz upload de um arquivo local para o servidor (o inverso de ftp_get()).
• ftp_fget() — baixa para um identificador de arquivo já aberto em vez de um caminho.
• ftp_size() — obtém o tamanho de um arquivo remoto antes de baixá-lo.
• ftp_connect() e ftp_login() — abrem e autenticam a conexão.
• ftp_close() — fecha a conexão quando você terminar.

Resumo

ftp_get() baixa um arquivo remoto via FTP e o salva localmente, retornando true em caso de sucesso e false em caso de falha. Conecte-se e faça login primeiro, prefira FTP_BINARY a menos que você precise especificamente da conversão de terminação de linha ASCII, ative o modo passivo quando estiver atrás de um firewall e sempre verifique o valor de retorno para que as falhas não passem silenciosamente.

Prática