ftp_size()

Die PHP ftp_size()-Funktion

ftp_size() ist eine eingebaute PHP-Funktion, die einen FTP-Server nach der Größe einer einzelnen Remote-Datei in Bytes fragt. Sie verwenden sie, wenn Sie wissen müssen, wie groß eine Datei ist, ohne sie herunterzuladen — zum Beispiel um eine Fortschrittsanzeige zu rendern, zu prüfen ob sich eine Datei seit dem letzten Abgleich geändert hat, leere Dateien zu überspringen oder sicherzustellen, dass ein Upload die erwartete Größe hat.

Diese Seite behandelt die Signatur, ein vollständiges Funktionsbeispiel, die eine Falle, über die fast alle stolpern (passiver Modus), und den Umgang mit den speziellen Rückgabewerten.

Syntax

ftp_size(FTP\Connection $ftp, string $filename): int

Rückgabewert: die Dateigröße in Bytes als Integer bei Erfolg, oder -1 bei einem Fehler.

Wichtig: ftp_size() gibt bei einem Fehler den Integer -1 zurück — nicht false. Dies unterscheidet sich von den meisten anderen FTP-Funktionen. Vergleichen Sie daher immer mit -1, nicht mit false.

Vor PHP 8.1 war das Argument $ftp vom Typ resource; ab PHP 8.1 ist es ein FTP\Connection-Objekt. Ihr Code ändert sich dabei nicht — nur der zugrunde liegende Typ ändert sich.

Grundlegende Verwendung

Um ftp_size() aufzurufen, öffnen Sie zunächst eine Verbindung mit ftp_connect() und authentifizieren sich mit ftp_login():

<?php

// Open a connection to the FTP server
$conn = ftp_connect('ftp.example.com');

// Log in with your credentials
ftp_login($conn, 'username', 'password');

// Turn on passive mode (see the note below — this is almost always required)
ftp_pasv($conn, true);

// Ask the server how big the file is
$size = ftp_size($conn, '/public_html/index.php');

if ($size !== -1) {
    echo "The file is {$size} bytes.";
} else {
    echo "Could not determine the file size.";
}

// Always close the connection when you are done
ftp_close($conn);

Passiver Modus: Die häufigste Fehlerquelle

Wenn ftp_size() immer wieder -1 zurückgibt, obwohl die Datei eindeutig existiert, liegt die Ursache meist beim aktiven vs. passiven Modus und nicht an einem Tippfehler im Pfad. Hinter einer Firewall oder NAT (was auf die meisten Server von heute zutrifft) kann der FTP-Server keinen Datenkanal zurück zu Ihrem Client öffnen, weshalb der zugrunde liegende SIZE-Befehl hängt.

Rufen Sie ftp_pasv() nach dem Einloggen auf, um in den passiven Modus zu wechseln, in dem Ihr Client jede Verbindung selbst initiiert:

<?php
ftp_login($conn, 'username', 'password');
ftp_pasv($conn, true); // do this before ftp_size(), ftp_get(), ftp_nlist(), etc.

Der Übertragungsmodus beeinflusst das Ergebnis

Die Größe, die ein FTP-Server zurückmeldet, kann vom aktuellen Übertragungsmodus abhängen. Im ASCII-Modus übersetzen manche Server Zeilenenden, sodass die gemeldete Größe möglicherweise nicht mit der Byteanzahl im Binärmodus übereinstimmt. Für genaue Byte-für-Byte-Größen stellen Sie sicher, dass Sie im Binärmodus (FTP_BINARY) arbeiten. Dieser ist bei den meisten Servern für Größenabfragen der Standard und fast immer der richtige Modus für Nicht-Textdateien.

Robuste Fehlerbehandlung

Da ftp_size() einen Fehler mit -1 signalisiert, prüft ein zuverlässiger Wrapper genau auf diesen Wert und gibt eine Warnung aus, wenn die Größe unbekannt ist:

<?php

function remoteFileSize($conn, string $path): ?int
{
    $size = ftp_size($conn, $path);

    if ($size === -1) {
        // The file is missing, the path is wrong, or the SIZE command failed.
        return null;
    }

    return $size;
}

$size = remoteFileSize($conn, '/public_html/index.php');

echo $size === null
    ? "File not found or size unavailable.\n"
    : "Size: {$size} bytes\n";

Die Verwendung von null für den Fehlerfall verhindert, dass -1 in spätere Berechnungen einfließt (wo es Gesamtergebnisse stillschweigend verfälschen würde).

Größen mehrerer Dateien auflisten

ftp_size() arbeitet immer auf einem Pfad gleichzeitig. Um die Größen für ein ganzes Verzeichnis auszugeben, kombinieren Sie es mit ftp_nlist(), das ein array von Dateinamen zurückgibt:

<?php

$files = ftp_nlist($conn, '/public_html');

if ($files !== false) {
    foreach ($files as $file) {
        $size = ftp_size($conn, $file);
        $label = $size === -1 ? 'directory or unreadable' : "{$size} bytes";
        echo "{$file}: {$label}\n";
    }
}

Beachten Sie, dass ftp_size() für Verzeichnisse -1 zurückgibt — eine praktische Möglichkeit, in einer Auflistung zwischen Dateien und Ordnern zu unterscheiden.

Verwandte Funktionen

• ftp_connect() — Öffnet die Verbindung, die an ftp_size() übergeben wird.
• ftp_login() — Authentifizierung vor einer Größenabfrage.
• ftp_pasv() — Aktiviert den passiven Modus, damit ftp_size() erfolgreich ist.
• ftp_nlist() — Listet ein Verzeichnis auf, um die Größen vieler Dateien in einer Schleife abzufragen.
• ftp_get() — Lädt eine Datei herunter, sobald Sie ihre Größe kennen.
• ftp_close() — Schließt die Verbindung nach Abschluss.
• PHP FTP-Übersicht — Alle FTP-Funktionen auf einen Blick.

Fazit

ftp_size() ist der schnellste Weg, die Bytegröße einer Remote-Datei zu ermitteln, ohne sie zu übertragen. Denken Sie an die zwei Regeln, die es zuverlässig machen: Aktivieren Sie den passiven Modus mit ftp_pasv() nach dem Login, und testen Sie das Ergebnis gegen -1 (nicht false), um Fehler und Verzeichnisse zu erkennen.

Übung