ftp_nb_fget()

Entendendo a Função PHP ftp_nb_fget()

A função ftp_nb_fget() é uma função PHP embutida que recupera um arquivo de um servidor FTP e o grava em um arquivo local usando o modo não bloqueante. Este artigo fornece um guia completo para utilizá-la em seus projetos PHP.

O que é ftp_nb_fget()?

A função ftp_nb_fget() recupera um arquivo remoto e o grava em um ponteiro de arquivo local já aberto sem bloquear o script. Não bloqueante significa que a chamada retorna imediatamente em vez de pausar até que o arquivo inteiro seja transferido, para que seu script possa continuar fazendo outro trabalho enquanto o download ocorre em segundo plano.

Ela aceita quatro parâmetros (três obrigatórios, um opcional):

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

• FTP_FINISHED — a transferência foi concluída com sucesso.
• FTP_MOREDATA — a transferência ainda está em andamento; chame ftp_nb_continue() para continuar.
• FTP_FAILED — ocorreu um erro.

Bloqueante vs. não bloqueante: o equivalente bloqueante é ftp_fget(), que retorna somente quando o arquivo é totalmente transferido. Use ftp_nb_fget() quando quiser exibir progresso, executar outro trabalho ou transferir vários arquivos de forma quase paralela.

Sintaxe de ftp_nb_fget()

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

Sintaxe de ftp_nb_fget()

int ftp_nb_fget ( resource $ftp_stream , resource $handle , string $remote_file , int $mode [, int $resumepos = 0 ] )

Use FTP_BINARY para qualquer arquivo não textual (imagens, arquivos compactados, executáveis) para que os bytes sejam copiados literalmente; FTP_ASCII traduz as terminações de linha e deve ser usado apenas para arquivos de texto simples. O parâmetro resumepos é útil para continuar um arquivo parcialmente baixado: passe o tamanho do arquivo local para que a transferência continue de onde parou em vez de reiniciar.

Uso de ftp_nb_fget()

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

Uso de ftp_nb_fget()

<?php

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

// Open a file for writing
$handle = fopen('local_file.txt', 'w');

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

// 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);
}

// Check final result
if ($result === FTP_FINISHED) {
    echo "Download completed successfully.";
} else {
    echo "Download failed.";
}

fclose($handle);
ftp_close($conn);
?>

Neste exemplo, estabelecemos uma conexão com o servidor FTP usando ftp_connect(). Em seguida, fazemos login usando ftp_login(). Abrimos um arquivo para escrita com fopen() e iniciamos uma operação FTP assíncrona com ftp_nb_fget(). Continuamos a operação com ftp_nb_continue() dentro de um laço while que verifica a constante FTP_MOREDATA. Por fim, verificamos o resultado e fechamos o arquivo e a conexão FTP.

Tratamento de erros em ftp_nb_fget()

É importante tratar os erros corretamente ao usar a função ftp_nb_fget(). A função e ftp_nb_continue() retornam constantes de estado em vez de simples valores booleanos. Aqui está um exemplo de como tratar erros e verificar os estados de transferência:

Tratamento de erros em ftp_nb_fget()

<?php

// Assuming $conn is an established FTP connection
$handle = fopen('local_file.txt', 'w');
$result = ftp_nb_fget($conn, $handle, 'remote_file.txt', FTP_BINARY);

if ($result === FTP_FAILED) {
    echo "Failed to start download.\n";
} else {
    while ($result === FTP_MOREDATA) {
        $result = ftp_nb_continue($conn);
    }

    if ($result === FTP_FINISHED) {
        echo "Download completed successfully.\n";
    } else {
        echo "Download failed during transfer.\n";
    }
}

fclose($handle);
ftp_close($conn);
?>

Funções relacionadas

• ftp_fget() — a versão bloqueante que faz download para um ponteiro de arquivo aberto.
• ftp_nb_get() — download não bloqueante diretamente para um caminho local (sem necessidade de fopen()).
• ftp_nb_continue() — conduz a transferência iniciada por ftp_nb_fget().
• ftp_nb_fput() — o equivalente não bloqueante para upload.
• ftp_connect() e ftp_login() — abrem e autenticam a conexão.

Conclusão

A função ftp_nb_fget() recupera arquivos de um servidor FTP no modo não bloqueante, permitindo que seu script continue com outro trabalho enquanto o download prossegue. Sempre itere sobre ftp_nb_continue() enquanto o estado for FTP_MOREDATA e verifique a constante final (FTP_FINISHED ou FTP_FAILED) antes de considerar o arquivo completo.

Nota: A extensão FTP é considerada legada. Para aplicações modernas, prefira SFTP (via a extensão ssh2 ou phpseclib) ou clientes HTTP assíncronos para melhor segurança e desempenho.

Prática