Entendendo a função PHP ftp_alloc()

A extensão FTP do PHP permite mover arquivos entre o seu script e um servidor remoto. A função ftp_alloc() é o "aviso prévio" que você envia antes de um upload: ela pede ao servidor que reserve espaço em disco para um arquivo que você está prestes a transferir. Esta página explica o que ftp_alloc() realmente faz, sua sintaxe e parâmetros, por que a maioria dos uploads não a utiliza, e como interpretar a mensagem de diagnóstico que ela retorna.

O que ftp_alloc() faz

ftp_alloc() envia o comando FTP ALLO (alocar) ao servidor conectado, solicitando que ele reserve um determinado número de bytes para um arquivo que você pretende enviar. Ela não cria o arquivo, grava nenhum dado nem transfere nada — apenas pergunta ao servidor se ele consegue acomodar um arquivo daquele tamanho.

O problema: o comando ALLO é opcional no protocolo FTP, e a grande maioria dos servidores FTP modernos o ignora e simplesmente retorna sucesso independentemente do espaço livre. Ele só era relevante para sistemas legados (mainframes, sistemas de arquivos orientados a registros) que precisavam pré-reservar armazenamento antes de uma gravação. Por isso, um resultado true não garante que o ftp_put() subsequente terá êxito, e você deve tratar ftp_alloc() como uma verificação consultiva, não como uma garantia real de espaço em disco.

Sintaxe

ftp_alloc(FTP\Connection $ftp, int $size, string &$response = null): bool

Valor de retorno: true em caso de sucesso, false em caso de falha. Desde o PHP 8.1, o argumento $ftp é um objeto FTP\Connection em vez de um resource, mas o uso permanece o mesmo.

Como usar ftp_alloc()

Você deve conectar e autenticar antes de chamar ftp_alloc(). O fluxo típico é: conectar, fazer login, mudar para o modo passivo e então alocar.

<?php

$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'username', 'password');
ftp_pasv($ftp, true);

$size = 1024; // bytes you intend to upload

// $response captures the server's reply by reference
if (ftp_alloc($ftp, $size, $response)) {
    echo "Allocated $size bytes. Server said: $response\n";
} else {
    echo "Allocation failed: $response\n";
}

ftp_close($ftp);

ftp_connect() abre a conexão, ftp_login() autentica, e ftp_pasv() coloca a sessão em modo passivo (mais seguro atrás de firewalls e NAT). O terceiro argumento para ftp_alloc() — $response — é preenchido por referência com a mensagem bruta do servidor, para que você possa registrar exatamente por que uma alocação foi recusada. Por fim, ftp_close() libera a conexão.

Um padrão prático: verificar antes de fazer upload

O uso mais útil de ftp_alloc() é como uma verificação antes de um upload real, para falhar antecipadamente em servidores que de fato respeitam o ALLO:

<?php

$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'username', 'password');
ftp_pasv($ftp, true);

$localFile  = 'report.pdf';
$remoteFile = 'uploads/report.pdf';
$size       = filesize($localFile); // bytes the upload will need

if (!ftp_alloc($ftp, $size, $response)) {
    echo "Server refused to reserve {$size} bytes: $response\n";
} elseif (ftp_put($ftp, $remoteFile, $localFile, FTP_BINARY)) {
    echo "Uploaded $localFile to $remoteFile\n";
} else {
    echo "Upload failed even though allocation succeeded.\n";
}

ftp_close($ftp);

Aqui filesize() fornece a contagem exata de bytes, ftp_alloc() faz a verificação consultiva e ftp_put() realiza a transferência real em modo binário.

Armadilhas comuns

• A maioria dos servidores ignora o ALLO. Um retorno true muitas vezes significa "comando aceito", não "espaço verificado". Sempre trate um possível erro de upload depois.
• Ela não cria nem faz upload de um arquivo. Use ftp_put() ou ftp_fput() para a transferência real.
• Passe $size em bytes. Para um upload real, obtenha o valor com filesize() em vez de adivinhar.
• Leia $response. Como ele é preenchido por referência, é sua única janela para entender por que o servidor recusou — registre-o.
• Ela não informa o tamanho de um arquivo remoto. Para isso, use ftp_size().

Conclusão

ftp_alloc() envia uma requisição FTP ALLO para reservar espaço para um upload futuro e relata a resposta do servidor por meio de um parâmetro por referência. Na prática, é uma etapa consultiva que a maioria dos servidores modernos ignora, então combine-a com um tratamento de erros adequado em torno da sua chamada real a ftp_put(). Para saber mais sobre as funções PHP em geral, consulte o capítulo de funções PHP.

Prática