ftp_fput()

O que é ftp_fput()?

A função ftp_fput() é uma função nativa do PHP que faz upload de um arquivo para o servidor FTP. A função recebe cinco parâmetros:

1. ftp_stream: O identificador de conexão retornado pela função ftp_connect().
2. remote_file: O nome do arquivo remoto para o qual o arquivo será enviado.
3. local_file: Um recurso de handle de arquivo aberto com fopen() que aponta para o arquivo local a ser enviado.
4. mode (opcional): O modo de transferência (FTP_ASCII ou FTP_BINARY). O padrão é FTP_ASCII.
5. startpos (opcional): A posição inicial no arquivo remoto para o upload. O padrão é 0.

A função retorna um valor boolean. Se o upload do arquivo for bem-sucedido, ela retorna true. Caso contrário, retorna false.

Quando usar ftp_fput() em vez de ftp_put()

ftp_put() recebe um caminho de arquivo local como string e abre o arquivo para você. Já ftp_fput() recebe um handle de arquivo já aberto. Use ftp_fput() quando:

• Os dados que você deseja enviar não são um arquivo comum em disco — por exemplo, um stream temporário criado com php://temp, ou a saída de outro recurso que você já tem aberto.
• Você precisa de controle preciso sobre a posição de leitura (combinado com o parâmetro startpos, é possível retomar um upload interrompido).
• Você já abriu o handle por outro motivo e deseja evitar abrir o mesmo arquivo duas vezes.

Se você simplesmente quer fazer upload de um arquivo existente pelo nome, ftp_put() é mais simples. Para uploads não bloqueantes (assíncronos), consulte ftp_nb_fput().

Sintaxe de ftp_fput()

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

Sintaxe de ftp_fput()

bool ftp_fput ( resource $ftp_stream , string $remote_file , resource $local_file [, int $mode = FTP_ASCII [, int $startpos = 0 ]] )

Uso de ftp_fput()

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

Uso de ftp_fput() em PHP

<?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.");
}

// Open the local file
$local_file = fopen('/local/directory/local_file.txt', 'r');
if (!$local_file) {
    die("Could not open local file.");
}

// Upload the file to the remote FTP server
if (ftp_fput($conn, 'remote_file.txt', $local_file, FTP_ASCII)) {
    echo "File uploaded successfully.\n";
} else {
    echo "Failed to upload the file.\n";
}

// Close the file handle and FTP connection
fclose($local_file);
ftp_close($conn);

Neste exemplo, estabelecemos uma conexão com o servidor FTP usando a função ftp_connect() e verificamos se ela foi bem-sucedida. Em seguida, fazemos login com nossas credenciais FTP usando ftp_login() e verificamos se há erros. Depois, abrimos o arquivo local com fopen() para obter o handle de arquivo necessário. Por fim, fazemos o upload do arquivo para o servidor FTP remoto usando ftp_fput() e fechamos tanto o handle de arquivo quanto a conexão FTP com ftp_close().

Escolhendo o modo de transferência: FTP_ASCII vs FTP_BINARY

O parâmetro mode controla como os bytes são transferidos e tem mais importância do que parece:

• FTP_BINARY transfere o arquivo byte a byte, sem alterações. Use-o para imagens, arquivos compactados, executáveis, PDFs — qualquer coisa que não seja texto simples. Este é o padrão seguro para quase tudo.
• FTP_ASCII traduz as terminações de linha entre as plataformas local e remota (por exemplo, \n ↔ \r\n). É adequado apenas para arquivos de texto simples; usá-lo em dados binários corrompê-los-á silenciosamente.

Ao abrir o handle local, combine o modo do fopen() com a transferência: use 'rb' (leitura binária) junto com FTP_BINARY para que o PHP não altere os bytes durante a leitura:

<?php

$local_file = fopen('/local/directory/photo.jpg', 'rb');
ftp_fput($conn, 'photo.jpg', $local_file, FTP_BINARY);
fclose($local_file);

Tratamento de erros em ftp_fput()

É importante tratar os erros adequadamente ao usar a função ftp_fput(). Se a função retornar false, significa que o arquivo não pôde ser enviado por algum motivo. Veja um exemplo de como tratar erros:

Tratamento de erros em ftp_fput()

<?php

// Assuming $conn is already established via ftp_connect() and ftp_login()
$local_file = fopen('/local/directory/local_file.txt', 'rb');

if ($local_file === false) {
    echo "Could not open the local file.\n";
} elseif (ftp_fput($conn, 'remote_file.txt', $local_file, FTP_BINARY)) {
    echo "File uploaded successfully.\n";
    fclose($local_file);
} else {
    echo "Failed to upload the file.\n";
    fclose($local_file);
}

Observe a ordem das verificações: primeiro confirmamos que fopen() retornou um handle válido, depois chamamos ftp_fput(). Chamar fclose() em um handle false (o que ocorre quando o exemplo original pula a verificação de abertura) emite um aviso, por isso fechamos o handle apenas nos ramos em que ele foi realmente aberto. Isso garante que a mensagem de "sucesso" nunca seja exibida quando o upload não ocorreu.

Armadilhas comuns

• Passar um caminho em vez de um handle. ftp_fput() espera o recurso retornado por fopen(), não uma string com o nome do arquivo. Se você tiver um caminho, use ftp_put().
• Modo de transferência errado. Fazer upload de um arquivo binário com FTP_ASCII o corrompe. Na dúvida, use FTP_BINARY.
• Não fechar o handle. Sempre chame fclose() após a conclusão da transferência para liberar o recurso.
• Modo passivo. Por trás de um firewall, muitos servidores exigem o modo passivo. Chame ftp_pasv($conn, true) após o login se os uploads ficarem travados.

Conclusão

A função ftp_fput() faz o upload de um arquivo para um servidor FTP a partir de um handle de arquivo aberto, sendo a escolha certa quando seus dados já existem em um stream em vez de estarem em um caminho fixo no disco. Combine-a com o modo de transferência correto, verifique os valores de retorno de fopen() e ftp_fput(), e feche seus handles — assim ela funcionará de forma confiável em seus projetos PHP.

Prática