ftp_nb_get()

Entendendo a função PHP ftp_nb_get()

A função ftp_nb_get() faz o download de um arquivo de um servidor FTP em modo não bloqueante. Ao contrário de sua equivalente bloqueante ftp_get(), que interrompe o script até que todo o arquivo seja transferido, ftp_nb_get() devolve o controle ao seu programa quase imediatamente, permitindo que você realize outras tarefas enquanto o download é executado em segundo plano.

Esta página explica quando usar a variante não bloqueante, percorre cada parâmetro e valor de retorno, e mostra um padrão completo de uso com ftp_nb_continue().

Quando usar o modo não bloqueante

O "nb" no nome significa non-blocking (não bloqueante). Utilize ftp_nb_get() em vez de ftp_get() quando:

• Você quiser exibir o progresso ou manter uma interface responsiva enquanto um arquivo grande é baixado.
• Você precisar intercalar outras tarefas (registro de logs, envio de heartbeats, processamento de dados já baixados) durante a transferência.
• Você quiser aplicar sua própria lógica de timeout ou cancelamento no loop de verificação.

Para um simples "baixar este arquivo e aguardar", o ftp_get() padrão é mais simples e a melhor escolha. A desvantagem é que o modo não bloqueante exige que você controle a transferência manualmente em um loop com ftp_nb_continue().

O que é ftp_nb_get()?

A função ftp_nb_get() inicia um download de arquivo assíncrono. Ela requer quatro parâmetros:

1. ftp_stream: O identificador de conexão retornado por ftp_connect().
2. local_file: O caminho local onde o arquivo baixado será salvo.
3. remote_file: O caminho para o arquivo remoto no servidor FTP.
4. mode: O modo de transferência, FTP_ASCII ou FTP_BINARY.

Ela também aceita um quinto parâmetro opcional, resumepos, que especifica a posição no arquivo remoto a partir da qual o download deve ser iniciado (padrão 0).

A função retorna uma de três constantes:

Como a função pode retornar antes de o download terminar, você quase sempre a combina com ftp_nb_continue() em um loop que executa enquanto o resultado for FTP_MOREDATA.

Sintaxe de ftp_nb_get()

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

Sintaxe de ftp_nb_get()

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

A função ftp_nb_get() recebe quatro parâmetros obrigatórios (ftp_stream, local_file, remote_file e mode) e um parâmetro opcional (resumepos). O parâmetro ftp_stream é o identificador de conexão retornado por ftp_connect(). O parâmetro local_file é o caminho para o arquivo local onde o arquivo baixado será salvo. O parâmetro remote_file é o caminho para o arquivo remoto no servidor FTP. O parâmetro mode especifica o modo de transferência, FTP_ASCII ou FTP_BINARY. O parâmetro resumepos especifica a posição no arquivo remoto a partir da qual o download deve ser iniciado. Por padrão, resumepos é definido como 0, o que significa que o download começará do início do arquivo.

Uso de ftp_nb_get()

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

Uso de ftp_nb_get()

<?php

// Set up an FTP connection
$conn = ftp_connect('ftp.example.com');

// Login with your FTP credentials
ftp_login($conn, 'username', 'password');

// Initiate an asynchronous FTP operation
$result = ftp_nb_get($conn, 'local_file.txt', 'remote_file.txt', FTP_BINARY);

if ($result === FTP_FAILED) {
    echo "Failed to download file from remote server.\n";
} else {
    // Continue the asynchronous FTP operation
    while ($result === FTP_MOREDATA) {
        // Do something else while waiting for the FTP operation to complete
        $result = ftp_nb_continue($conn);
    }
}

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

Neste exemplo, estabelecemos uma conexão com o servidor FTP usando ftp_connect(). Em seguida, fazemos login com nossas credenciais FTP usando ftp_login(). Iniciamos uma operação FTP assíncrona com ftp_nb_get(). Continuamos a operação usando ftp_nb_continue() dentro de um loop que verifica FTP_MOREDATA e, por fim, encerramos a conexão FTP.

Retomando um download interrompido

O quinto parâmetro opcional, resumepos, permite continuar um arquivo parcialmente baixado em vez de recomeçar do zero. Passe o offset em bytes para retomar — geralmente o tamanho do arquivo que você já possui no disco:

Retomando um download com resumepos

<?php

$local = 'big-archive.zip';

// If a partial file already exists, resume from where it left off.
$resumePos = file_exists($local) ? filesize($local) : 0;

$result = ftp_nb_get($conn, $local, 'big-archive.zip', FTP_BINARY, $resumePos);

while ($result === FTP_MOREDATA) {
    $result = ftp_nb_continue($conn);
}

Isso é especialmente útil para arquivos grandes em conexões instáveis, onde você não quer baixar novamente dados que já possui.

Tratamento de erros em ftp_nb_get()

Sempre verifique o valor de retorno. ftp_nb_get() retorna FTP_FAILED quando não consegue iniciar (ou continuar) a transferência, e ftp_nb_continue() também pode retornar FTP_FAILED no meio do processo. Trate ambos os casos:

Tratamento de erros em ftp_nb_get()

<?php

$conn = ftp_connect('ftp.example.com');

if ($conn === false || !ftp_login($conn, 'username', 'password')) {
    exit("Could not connect or log in to the FTP server.\n");
}

$result = ftp_nb_get($conn, 'local_file.txt', 'remote_file.txt', FTP_BINARY);

// Drive the transfer to completion, watching for failure at every step.
while ($result === FTP_MOREDATA) {
    $result = ftp_nb_continue($conn);
}

if ($result === FTP_FINISHED) {
    echo "File downloaded successfully.\n";
} else {
    echo "Failed to download file from remote server.\n";
}

ftp_close($conn);

Ao verificar a conexão, o login e o estado final da transferência separadamente, você consegue identificar exatamente onde uma operação FTP falhou.

Funções relacionadas

• ftp_get() — a versão bloqueante que faz o download de um arquivo e aguarda sua conclusão.
• ftp_nb_continue() — continua uma transferência não bloqueante iniciada por ftp_nb_get().
• ftp_nb_fget() — semelhante a ftp_nb_get(), mas grava em um ponteiro de arquivo aberto em vez de um caminho.
• ftp_connect() e ftp_login() — estabelecem e autenticam a sessão FTP.
• ftp_close() — encerra a conexão quando você terminar.

Conclusão

A função ftp_nb_get() faz o download de arquivos de um servidor FTP em modo não bloqueante, permitindo que seu script permaneça responsivo enquanto uma transferência está em execução. Combine-a com ftp_nb_continue() em um loop, verifique o valor de retorno contra FTP_FINISHED e FTP_FAILED, e use resumepos para retomar downloads interrompidos.

Prática