Die PHP-Funktion ftp_alloc() verstehen

PHPs FTP-Erweiterung ermöglicht es, Dateien zwischen Ihrem Skript und einem Remote-Server zu verschieben. Die Funktion ftp_alloc() ist das höfliche „Vorab-Signal", das Sie vor einem Upload senden: Sie fordert den Server auf, Speicherplatz für eine Datei zu reservieren, die Sie gleich übertragen möchten. Diese Seite erklärt, was ftp_alloc() tatsächlich tut, welche Syntax und Parameter es hat, warum die meisten Uploads es nicht benötigen und wie die zurückgegebene Diagnosemeldung zu lesen ist.

Was ftp_alloc() bewirkt

ftp_alloc() sendet den FTP-Befehl ALLO (allocate) an den verbundenen Server und fordert ihn auf, eine bestimmte Anzahl von Bytes für eine Datei zu reservieren, die Sie hochladen möchten. Die Funktion erstellt weder die Datei, noch schreibt sie Daten oder überträgt etwas — sie fragt den Server lediglich, ob er eine Datei dieser Größe aufnehmen kann.

Der Haken: Der ALLO-Befehl ist im FTP-Protokoll optional, und die überwiegende Mehrheit moderner FTP-Server ignoriert ihn und gibt einfach Erfolg zurück, unabhängig vom freien Speicherplatz. Er war nur für Legacy-Systeme relevant (Mainframes, record-orientierte Dateisysteme), die Speicher vor einem Schreibvorgang vorbelegen mussten. Daher garantiert ein true-Ergebnis nicht, dass das anschließende ftp_put() erfolgreich ist. Behandeln Sie ftp_alloc() eher als unverbindliche Prüfung denn als echte Speicherplatzgarantie.

Syntax

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

Rückgabewert: true bei Erfolg, false bei Fehler. Seit PHP 8.1 ist das Argument $ftp ein FTP\Connection-Objekt statt einer Ressource, die Verwendung bleibt jedoch unverändert.

Verwendung von ftp_alloc()

Vor dem Aufruf von ftp_alloc() müssen Sie eine Verbindung herstellen und sich authentifizieren. Der typische Ablauf ist: Verbinden, einloggen, in den passiven Modus wechseln, dann reservieren.

<?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() öffnet die Verbindung, ftp_login() authentifiziert, und ftp_pasv() versetzt die Sitzung in den passiven Modus (sicherer hinter Firewalls und NAT). Das dritte Argument von ftp_alloc() — $response — wird per Referenz mit der rohen Serverantwort befüllt, sodass Sie genau protokollieren können, warum eine Reservierung abgelehnt wurde. Abschließend gibt ftp_close() die Verbindung frei.

Ein praktisches Muster: Vor dem Upload prüfen

Am nützlichsten ist ftp_alloc() als Absicherung vor einem echten Upload, um bei Servern, die ALLO tatsächlich berücksichtigen, frühzeitig zu scheitern:

<?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);

Hier liefert filesize() die genaue Byteanzahl, ftp_alloc() führt die unverbindliche Prüfung durch, und ftp_put() führt die eigentliche Übertragung im Binärmodus durch.

Häufige Fallstricke

• Die meisten Server ignorieren ALLO. Ein true-Rückgabewert bedeutet oft nur „Befehl akzeptiert", nicht „Speicherplatz bestätigt". Behandeln Sie mögliche Upload-Fehler danach immer entsprechend.
• Die Funktion erstellt oder lädt keine Datei hoch. Verwenden Sie ftp_put() oder ftp_fput() für die eigentliche Übertragung.
• Geben Sie $size in Bytes an. Für einen echten Upload ermitteln Sie den Wert lieber über filesize() als zu schätzen.
• Lesen Sie $response aus. Da es per Referenz befüllt wird, ist es Ihr einziges Fenster dafür, warum der Server abgelehnt hat — protokollieren Sie es.
• Die Funktion verrät Ihnen nicht die Größe einer Remote-Datei. Verwenden Sie dafür ftp_size().

Fazit

ftp_alloc() sendet eine FTP-ALLO-Anfrage, um Speicherplatz für einen bevorstehenden Upload zu reservieren, und meldet die Serverantwort über einen per-Referenz-Parameter zurück. In der Praxis ist es ein unverbindlicher Schritt, den die meisten modernen Server ignorieren. Kombinieren Sie es daher mit einer ordentlichen Fehlerbehandlung rund um Ihren eigentlichen ftp_put()-Aufruf. Weitere Informationen zu PHP-Funktionen im Allgemeinen finden Sie im Kapitel PHP-Funktionen.

Übungen