Understanding the PHP function ftp_alloc()

PHP's FTP extension lets you move files between your script and a remote server. The ftp_alloc() function is the polite "heads up" you send before an upload: it asks the server to reserve disk space for a file you are about to transfer. This page covers what ftp_alloc() actually does, its syntax and parameters, why most uploads don't need it, and how to read the diagnostic message it returns.

What ftp_alloc() does

ftp_alloc() sends the FTP ALLO (allocate) command to the connected server, requesting that it set aside a given number of bytes for a file you intend to upload. It does not create the file, write any data, or transfer anything — it only asks the server whether it can accommodate a file of that size.

The catch: the ALLO command is optional in the FTP protocol, and the vast majority of modern FTP servers ignore it and simply return success regardless of free space. It only mattered for legacy systems (mainframes, record-oriented filesystems) that needed to pre-reserve storage before a write. Because of this, a true result does not guarantee the later ftp_put() will succeed, and you should treat ftp_alloc() as an advisory check rather than a real disk-space guarantee.

Syntax

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

Return value: true on success, false on failure. Since PHP 8.1 the $ftp argument is an FTP\Connection object rather than a resource, but usage is unchanged.

How to use ftp_alloc()

You must connect and authenticate before calling ftp_alloc(). The typical flow is: connect, log in, switch to passive mode, then allocate.

<?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() opens the connection, ftp_login() authenticates, and ftp_pasv() puts the session into passive mode (safer behind firewalls and NAT). The third argument to ftp_alloc() — $response — is filled in by reference with the server's raw message, so you can log exactly why an allocation was refused. Finally ftp_close() releases the connection.

A practical pattern: check before uploading

Where ftp_alloc() is most useful is as a guard in front of a real upload, so you can fail early on servers that do honor 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);

Here filesize() gives the exact byte count, ftp_alloc() does the advisory check, and ftp_put() performs the actual transfer in binary mode.

Common gotchas

• Most servers ignore ALLO. A true return often means "command accepted," not "space verified." Always handle a possible upload failure afterward.
• It does not create or upload a file. Use ftp_put() or ftp_fput() for the actual transfer.
• Pass $size in bytes. For a real upload, derive it from filesize() rather than guessing.
• Read $response. Because it is filled by reference, it is your only window into why the server refused — log it.
• It will not tell you a remote file's size. For that, use ftp_size().

Conclusion

ftp_alloc() sends an FTP ALLO request to reserve space for an upcoming upload and reports the server's reply through a by-reference parameter. In practice it is an advisory step that most modern servers ignore, so pair it with proper error handling around your actual ftp_put() call. For more on PHP functions in general, see the PHP functions chapter.

Practice