ftp_put()

A função PHP ftp_put()

ftp_put() é uma função nativa do PHP que faz upload de um arquivo local para um servidor FTP remoto. Ela é a contraparte de upload de ftp_get(), que baixa um arquivo remoto para a sua máquina. Esta página abrange a assinatura, os modos de transferência, um fluxo de trabalho completo, o tratamento de erros e as armadilhas que costumam causar problemas em produção.

Você usa ftp_put() após abrir uma conexão com ftp_connect() e autenticar com ftp_login().

Sintaxe

ftp_put(
    FTP\Connection $ftp,
    string $remote_filename,
    string $local_filename,
    int $mode = FTP_BINARY
): bool

Retorna true em caso de sucesso e false em caso de falha.

Nota de versão: Antes do PHP 8.1, o primeiro argumento era um resource retornado por ftp_connect(). A partir do PHP 8.1, é um objeto FTP\Connection. O seu código não muda — você continua passando o que ftp_connect() retorna — mas verificações com is_resource() não funcionam mais sobre ele.

Modo binário vs. ASCII

Escolher o modo errado é a causa mais comum de "o upload funcionou, mas o arquivo está corrompido":

• FTP_BINARY transfere os bytes exatamente como estão. Use-o para tudo por padrão — imagens, arquivos compactados, PDFs, executáveis e até texto na prática.
• FTP_ASCII reescreve os finais de linha (\n ↔ \r\n) para corresponder à plataforma de destino. Só faz sentido para texto simples e vai silenciosamente corromper qualquer arquivo binário. Na dúvida, fique com FTP_BINARY.

Um upload completo

Sempre verifique os valores de retorno de cada chamada FTP em vez de presumir que a etapa foi bem-sucedida:

<?php

// 1. Open a connection (false on failure)
$ftp = ftp_connect('ftp.example.com');
if ($ftp === false) {
    exit("Could not connect to FTP server.\n");
}

// 2. Authenticate
if (!ftp_login($ftp, 'username', 'password')) {
    ftp_close($ftp);
    exit("FTP login failed.\n");
}

// 3. Behind a firewall/NAT? Passive mode is almost always required.
ftp_pasv($ftp, true);

// 4. Upload: local file -> remote path, binary mode
$ok = ftp_put($ftp, '/public_html/index.html', './build/index.html', FTP_BINARY);

echo $ok
    ? "Upload succeeded.\n"
    : "Upload failed.\n";

// 5. Always close
ftp_close($ftp);

Observe a ordem dos argumentos: destino remoto primeiro, origem local depois — o inverso do que muitas pessoas esperam. Trocá-los faz o PHP tentar ler um arquivo local inexistente e a chamada falha.

Tratamento de erros

ftp_put() retorna false e emite um aviso PHP em caso de falha. Converta isso em um resultado claro e acionável em vez de deixar um aviso indesejado vazar para a sua saída:

<?php

$remote = '/public_html/index.html';
$local  = './build/index.html';

// Catch the "no such local file" case before touching the network.
if (!is_readable($local)) {
    exit("Local file '$local' is missing or unreadable.\n");
}

if (!ftp_put($ftp, $remote, $local, FTP_BINARY)) {
    // Common causes: wrong remote directory, no write permission,
    // disk quota exceeded, or passive mode not enabled.
    echo "Failed to upload '$local' to '$remote'.\n";
} else {
    echo "Uploaded '$local' to '$remote'.\n";
}

ftp_close($ftp);

Causas comuns de falha

• Ordem errada dos argumentos — caminho remoto e caminho local invertidos.
• Modo passivo não definido — a maioria dos servidores atrás de NAT precisam de ftp_pasv($ftp, true) após o login.
• Diretório remoto inexistente — ftp_put() não cria pastas; use ftp_mkdir() primeiro.
• Sem permissão de escrita ou cota excedida no lado do servidor.
• Modo de transferência errado corrompendo um arquivo binário (use FTP_BINARY).

Upload a partir de um stream aberto

Se os seus dados já estão em um identificador de arquivo aberto (ou vêm de um wrapper de stream em vez de um caminho em disco), use ftp_fput() — ele recebe um recurso de stream no lugar de um nome de arquivo local.

Conclusão

ftp_put() faz upload de um arquivo local para um servidor FTP remoto. Lembre-se das três coisas que causam a maioria dos problemas: passe o caminho remoto primeiro, mantenha FTP_BINARY a menos que tenha um motivo específico para usar ASCII, e verifique todos os valores de retorno. Para transferências não bloqueantes que não travam o seu script, veja ftp_nb_put().

Prática