Comprender la función PHP ftp_alloc()

La extensión FTP de PHP te permite mover archivos entre tu script y un servidor remoto. La función ftp_alloc() es el "aviso previo" que envías antes de una subida: le pide al servidor que reserve espacio en disco para un archivo que estás a punto de transferir. Esta página explica qué hace realmente ftp_alloc(), su sintaxis y parámetros, por qué la mayoría de las subidas no la necesitan, y cómo leer el mensaje de diagnóstico que devuelve.

Qué hace ftp_alloc()

ftp_alloc() envía el comando FTP ALLO (allocate) al servidor conectado, solicitándole que reserve una cantidad determinada de bytes para un archivo que se pretende subir. No crea el archivo, no escribe datos ni transfiere nada — simplemente pregunta al servidor si puede alojar un archivo de ese tamaño.

El problema: el comando ALLO es opcional en el protocolo FTP, y la gran mayoría de los servidores FTP modernos lo ignoran y simplemente devuelven éxito independientemente del espacio libre. Solo fue relevante para sistemas heredados (mainframes, sistemas de archivos orientados a registros) que necesitaban reservar almacenamiento antes de una escritura. Por ello, un resultado true no garantiza que el posterior ftp_put() tenga éxito, y debes tratar ftp_alloc() como una comprobación orientativa más que como una garantía real de espacio en disco.

Sintaxis

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

Valor de retorno: true en caso de éxito, false en caso de fallo. Desde PHP 8.1, el argumento $ftp es un objeto FTP\Connection en lugar de un recurso, pero el uso no cambia.

Cómo usar ftp_alloc()

Debes conectarte y autenticarte antes de llamar a ftp_alloc(). El flujo típico es: conectar, iniciar sesión, cambiar a modo pasivo y luego reservar.

<?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 la conexión, ftp_login() se autentica, y ftp_pasv() pone la sesión en modo pasivo (más seguro detrás de cortafuegos y NAT). El tercer argumento de ftp_alloc() — $response — se rellena por referencia con el mensaje sin procesar del servidor, para que puedas registrar exactamente por qué se rechazó una reserva. Por último, ftp_close() libera la conexión.

Un patrón práctico: comprobar antes de subir

Donde más útil resulta ftp_alloc() es como guardia antes de una subida real, de modo que puedas fallar rápido en los servidores que sí respetan 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);

Aquí filesize() proporciona el recuento exacto de bytes, ftp_alloc() realiza la comprobación orientativa, y ftp_put() ejecuta la transferencia real en modo binario.

Errores comunes

• La mayoría de los servidores ignoran ALLO. Un retorno true suele significar "comando aceptado", no "espacio verificado". Gestiona siempre un posible fallo de subida posterior.
• No crea ni sube un archivo. Usa ftp_put() o ftp_fput() para la transferencia real.
• Pasa $size en bytes. Para una subida real, obtén el valor de filesize() en lugar de adivinarlo.
• Lee $response. Al estar relleno por referencia, es la única forma de saber por qué el servidor rechazó la solicitud — regístralo.
• No te informará del tamaño de un archivo remoto. Para eso, usa ftp_size().

Conclusión

ftp_alloc() envía una solicitud FTP ALLO para reservar espacio para una próxima subida e informa de la respuesta del servidor a través de un parámetro por referencia. En la práctica es un paso orientativo que la mayoría de los servidores modernos ignoran, así que combínalo con un manejo adecuado de errores alrededor de tu llamada real a ftp_put(). Para más información sobre las funciones PHP en general, consulta el capítulo de funciones PHP.

Práctica