Guida alla funzione PHP ftp_alloc()

L'estensione FTP di PHP consente di spostare file tra il tuo script e un server remoto. La funzione ftp_alloc() è il "preavviso" che invii prima di un upload: chiede al server di riservare spazio su disco per un file che stai per trasferire. Questa pagina spiega cosa fa realmente ftp_alloc(), la sua sintassi e i suoi parametri, perché la maggior parte degli upload non ne ha bisogno e come leggere il messaggio diagnostico che restituisce.

Cosa fa ftp_alloc()

ftp_alloc() invia il comando FTP ALLO (allocate) al server connesso, richiedendo che riservi un determinato numero di byte per un file che intendi caricare. Non crea il file, non scrive dati né trasferisce nulla — si limita a chiedere al server se riesce ad accogliere un file di quella dimensione.

Il problema è che il comando ALLO è opzionale nel protocollo FTP, e la grande maggioranza dei server FTP moderni lo ignora e restituisce semplicemente successo indipendentemente dallo spazio libero. Era rilevante solo per sistemi legacy (mainframe, filesystem orientati ai record) che dovevano pre-riservare lo storage prima di una scrittura. Per questo motivo, un risultato true non garantisce che il successivo ftp_put() avrà successo, e dovresti trattare ftp_alloc() come un controllo indicativo piuttosto che una vera garanzia sullo spazio su disco.

Sintassi

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

Valore restituito: true in caso di successo, false in caso di errore. A partire da PHP 8.1 l'argomento $ftp è un oggetto FTP\Connection invece di una risorsa, ma l'utilizzo rimane invariato.

Come usare ftp_alloc()

Devi connetterti e autenticarti prima di chiamare ftp_alloc(). Il flusso tipico è: connettersi, accedere, passare alla modalità passiva, quindi allocare.

<?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() apre la connessione, ftp_login() effettua l'autenticazione e ftp_pasv() mette la sessione in modalità passiva (più sicura dietro firewall e NAT). Il terzo argomento di ftp_alloc() — $response — viene popolato per riferimento con il messaggio grezzo del server, così puoi registrare esattamente perché un'allocazione è stata rifiutata. Infine ftp_close() chiude la connessione.

Un pattern pratico: verificare prima di caricare

ftp_alloc() è più utile come guardia davanti a un upload reale, così puoi fallire subito sui server che onorano 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);

Qui filesize() fornisce il numero esatto di byte, ftp_alloc() effettua il controllo indicativo e ftp_put() esegue il trasferimento effettivo in modalità binaria.

Errori comuni

• La maggior parte dei server ignora ALLO. Un ritorno true spesso significa "comando accettato", non "spazio verificato". Gestisci sempre un possibile errore di upload successivo.
• Non crea né carica un file. Usa ftp_put() o ftp_fput() per il trasferimento effettivo.
• Passa $size in byte. Per un upload reale, ricavalo da filesize() invece di indovinare.
• Leggi $response. Poiché viene popolato per riferimento, è l'unica finestra su perché il server ha rifiutato — registralo.
• Non ti dirà la dimensione di un file remoto. Per questo, usa ftp_size().

Conclusione

ftp_alloc() invia una richiesta FTP ALLO per riservare spazio per un upload imminente e riporta la risposta del server attraverso un parametro per riferimento. In pratica è un passaggio indicativo che la maggior parte dei server moderni ignora, quindi abbinalo a una corretta gestione degli errori attorno alla tua chiamata effettiva a ftp_put(). Per ulteriori informazioni sulle funzioni PHP in generale, consulta il capitolo funzioni PHP.

Esercizio