ftp_nb_put()

Entendendo a Função PHP ftp_nb_put()

A função ftp_nb_put() é uma função nativa do PHP que envia um arquivo para um servidor FTP usando o modo não bloqueante. "Não bloqueante" significa que a chamada retorna imediatamente após iniciar a transferência, em vez de aguardar sua conclusão, para que o script possa continuar executando outras tarefas enquanto os dados trafegam pela rede. Este guia aborda seus parâmetros, sintaxe, uso e tratamento de erros para que você possa integrá-la de forma eficaz nos seus projetos PHP.

A função complementar é ftp_put(), que realiza o envio em modo bloqueante (o script pausa até que o upload seja concluído). Use ftp_nb_put() quando quiser enviar um arquivo grande enquanto exibe o progresso, processa outras tarefas ou evita uma requisição longa e travada.

O que é ftp_nb_put()?

A função ftp_nb_put() envia um arquivo para um servidor FTP sem interromper a execução do script. Ela aceita os seguintes parâmetros:

1. ftp_stream: O identificador de conexão retornado por ftp_connect() (um objeto FTP\Connection no PHP 8.1+).
2. remote_file: O caminho do arquivo remoto para onde o arquivo será enviado.
3. local_file: O caminho do arquivo local a ser lido.
4. mode: O modo de transferência, podendo ser FTP_BINARY ou FTP_ASCII (obrigatório antes do PHP 7.3; opcional e com padrão FTP_BINARY a partir da versão 7.3).
5. startpos (opcional): O deslocamento em bytes no arquivo remoto a partir do qual a escrita deve começar; o padrão é 0.

Ao contrário de um upload bloqueante, ftp_nb_put() não retorna simplesmente true/false. Em vez disso, retorna uma das três constantes inteiras:

Por causa desses valores de retorno, ftp_nb_put() é quase sempre usada em conjunto com ftp_nb_continue() em um loop, como mostrado abaixo.

Sintaxe de ftp_nb_put()

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

Sintaxe de ftp_nb_put()

int ftp_nb_put ( FTP\Connection $ftp_stream , string $remote_file , string $local_file , int $mode [, int $startpos = 0 ] )

A função ftp_nb_put() aceita três parâmetros obrigatórios (ftp_stream, remote_file e local_file) e um parâmetro opcional (startpos). O parâmetro mode é obrigatório e especifica o modo de transferência: FTP_BINARY é recomendado para a maioria dos arquivos (imagens, arquivos compactados, executáveis) para evitar corrupção de terminações de linha, enquanto FTP_ASCII é usado para arquivos de texto simples (embora FTP_BINARY seja geralmente mais seguro para todos os tipos de arquivo). O parâmetro startpos especifica a posição no arquivo remoto a partir da qual o upload deve começar. Por padrão, startpos é definido como 0, o que significa que o upload começará do início do arquivo.

Uso de ftp_nb_put()

Para usar a função ftp_nb_put(), você primeiro estabelece uma conexão com ftp_connect() e se autentica com ftp_login(). Em seguida, inicia o upload e o conduz em um loop até que ele seja concluído:

Uso de ftp_nb_put()

<?php

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

// Login with your FTP credentials
if (!ftp_login($conn, 'username', 'password')) {
    die('Login failed.');
}

// Initiate an asynchronous FTP operation
$result = ftp_nb_put($conn, 'remote_file.txt', 'local_file.txt', FTP_BINARY);
if ($result === FTP_FAILED) {
    die('Upload failed.');
}

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

if ($result === FTP_FINISHED) {
    echo "Upload completed successfully.\n";
}

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

Neste exemplo, conectamos ao servidor FTP, fazemos login com nossas credenciais e iniciamos o upload com ftp_nb_put(). A primeira chamada retorna FTP_MOREDATA, então entramos em um loop e chamamos repetidamente ftp_nb_continue() para enviar o próximo bloco — o comentário // Do something else indica onde você atualizaria uma barra de progresso ou executaria outro trabalho. Quando o loop termina, verificamos FTP_FINISHED para confirmar o sucesso e, em seguida, encerramos a conexão com ftp_close().

Nota: Sempre chame ftp_nb_continue() até que o resultado não seja mais FTP_MOREDATA. Se você parar antes, o upload ficará incompleto no servidor.

Tratamento de erros em ftp_nb_put()

É importante tratar os erros corretamente ao usar a função ftp_nb_put(). Se a função retornar FTP_FAILED, significa que o upload não foi bem-sucedido. Veja um exemplo de como tratar erros:

Tratamento de erros em ftp_nb_put()

<?php

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

if ($result === FTP_FAILED) {
    echo "Failed to upload file to remote server.\n";
}

while ($result === FTP_MOREDATA) {
    // Do something else while waiting for the FTP operation to complete
    $result = ftp_nb_continue($conn);
}

if ($result === FTP_FINISHED) {
    echo "Upload completed.\n";
}

ftp_close($conn);

Ao tratar os erros adequadamente e verificar o valor de retorno da função, você garante o sucesso das suas operações FTP usando a função ftp_nb_put().

Funções relacionadas

• ftp_put() — envia um arquivo em modo bloqueante (mais simples, mas pausa o script).
• ftp_nb_continue() — continua uma transferência não bloqueante iniciada por ftp_nb_put().
• ftp_nb_fput() — upload não bloqueante a partir de um identificador de arquivo já aberto, em vez de um caminho.
• ftp_nb_get() — o equivalente de download de ftp_nb_put().

Conclusão

A função ftp_nb_put() envia arquivos para um servidor FTP em modo não bloqueante, permitindo que o script continue com outras tarefas enquanto a transferência ocorre em segundo plano. O segredo é iniciar o upload, iterar com ftp_nb_continue() enquanto o status for FTP_MOREDATA e confirmar FTP_FINISHED (tratando FTP_FAILED) antes de encerrar a conexão. Com uso adequado e tratamento de erros, ela é uma ferramenta valiosa para transferências de arquivos responsivas nos seus projetos PHP.

Nota: As funções ftp_nb_* são consideradas legadas no PHP moderno. Para novos projetos, considere usar cURL ou uma biblioteca HTTP assíncrona como o Guzzle para melhor desempenho, segurança e suporte a protocolos mais amplos.

Prática