ftp_nb_fput()

Entendendo a Função PHP ftp_nb_fput()

A função ftp_nb_fput() é uma função PHP embutida que faz upload de um arquivo para um servidor FTP usando o modo não bloqueante. "Não bloqueante" significa que a função devolve o controle ao seu script antes que a transferência termine, permitindo que você execute outro código (atualizar uma barra de progresso, processar outra tarefa) enquanto o upload ainda está em andamento. Este artigo explica os parâmetros, os valores de retorno e um padrão completo de uso para aplicá-la em seus projetos PHP.

A contraparte bloqueante é ftp_fput(), que simplesmente aguarda até que o arquivo inteiro seja enviado. Use ftp_nb_fput() apenas quando precisar realizar outras operações durante a transferência.

O que é ftp_nb_fput()?

A função ftp_nb_fput() faz upload de um arquivo para um servidor FTP usando o modo não bloqueante. Ela aceita quatro parâmetros obrigatórios e um parâmetro opcional:

1. ftp_stream: O identificador de conexão retornado por ftp_connect().
2. remote_file: O caminho para o arquivo remoto no servidor FTP.
3. handle: Um ponteiro de arquivo aberto para o arquivo local.
4. mode: O modo de transferência, podendo ser FTP_ASCII ou FTP_BINARY.
5. startpos (opcional): A posição no arquivo remoto a partir da qual iniciar o upload. O padrão é 0.

A função retorna uma das seguintes constantes: FTP_SUCCESS (upload concluído), FTP_MOREDATA (há mais dados a serem lidos) ou FTP_FAILED (ocorreu um erro).

Sintaxe de ftp_nb_fput()

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

int ftp_nb_fput ( resource $ftp_stream , string $remote_file , resource $handle , int $mode [, int $startpos = 0 ] )

A função recebe quatro parâmetros obrigatórios (ftp_stream, remote_file, handle e mode) e um parâmetro opcional (startpos). O parâmetro ftp_stream é o identificador de conexão retornado por ftp_connect(). O parâmetro remote_file é o caminho para o arquivo remoto no servidor FTP. O parâmetro handle é um ponteiro de arquivo aberto no sistema de arquivos local. O parâmetro mode especifica o modo de transferência, podendo ser FTP_ASCII ou FTP_BINARY. O parâmetro startpos especifica a posição no arquivo remoto a partir da qual iniciar o upload. Por padrão, startpos é definido como 0, o que significa que o upload começará do início do arquivo.

Uso de ftp_nb_fput()

Para usar a função ftp_nb_fput(), primeiro você precisa estabelecer uma conexão com o servidor FTP usando a função ftp_connect() e autenticar-se com ftp_login(). Veja um exemplo completo:

<?php

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

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

// Enable passive mode to prevent transfer issues
ftp_pasv($conn, true);

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

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

// Continue the asynchronous FTP operation
while ($res == FTP_MOREDATA) {
    $res = ftp_nb_continue($conn);
}

// Check for errors
if ($res != FTP_FAILED && $res != FTP_SUCCESS) {
    echo "FTP upload failed.\n";
}

// Close the file
fclose($handle);

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

Neste exemplo, estabelecemos uma conexão com o servidor FTP, fazemos login com nossas credenciais e ativamos o modo passivo com ftp_pasv() para evitar problemas comuns de transferência por trás de firewalls. Abrimos o arquivo local para leitura e, em seguida, chamamos ftp_nb_fput() para iniciar o upload. O detalhe fundamental é o laço while: enquanto ftp_nb_fput() (ou as chamadas subsequentes) retornar FTP_MOREDATA, mantemos a transferência em andamento com ftp_nb_continue(). Em uma aplicação real, cada iteração desse laço é onde você realizaria outras operações, já que a transferência é não bloqueante.

Tratamento de erros em ftp_nb_fput()

É importante tratar os erros corretamente ao usar a função ftp_nb_fput(). A função retorna constantes específicas em vez de um boolean, portanto você deve verificar FTP_FAILED para detectar erros. Veja um exemplo de como tratar os erros:

<?php

// Assume $conn is already established and logged in
$handle = fopen('local_file.txt', 'r');
$res = ftp_nb_fput($conn, 'remote_file.txt', $handle, FTP_BINARY);

if ($res == FTP_FAILED) {
    echo "Failed to initiate upload.\n";
}

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

if ($res == FTP_FAILED) {
    echo "Failed to complete upload.\n";
}

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

Ao tratar os erros adequadamente e verificar as constantes de retorno de ftp_nb_fput() e ftp_nb_continue(), você garante o sucesso das suas operações FTP.

ftp_nb_fput() vs. funções relacionadas

O PHP oferece diversas funções de upload FTP. A escolha da mais adequada depende de você ter um ponteiro de arquivo aberto ou apenas um caminho, e de precisar ou não de comportamento não bloqueante:

• ftp_fput() — faz upload a partir de um ponteiro de arquivo aberto, bloqueando até a conclusão.
• ftp_put() — faz upload a partir de um caminho de arquivo local, bloqueando até a conclusão.
• ftp_nb_put() — upload não bloqueante a partir de um caminho de arquivo local (mesmo padrão de laço que esta função).
• ftp_nb_fput() — upload não bloqueante a partir de um ponteiro de arquivo aberto (esta função).

Todas as variantes não bloqueantes compartilham o mesmo laço FTP_MOREDATA / ftp_nb_continue().

Conclusão

A função ftp_nb_fput() faz upload de um arquivo para um servidor FTP em modo não bloqueante, permitindo que seu script continue executando outras operações enquanto a transferência está em andamento. O padrão essencial é: iniciar o upload, fazer um laço com ftp_nb_continue() enquanto o valor de retorno for FTP_MOREDATA, e verificar FTP_FAILED em cada etapa. Usada corretamente, ela melhora a responsividade do código de transferência de arquivos nos seus projetos PHP.

Prática