ftp_mdtm()

Was ist ftp_mdtm()?

Die Funktion ftp_mdtm() ist eine in PHP integrierte Funktion, die den Zeitpunkt der letzten Änderung einer einzelnen Datei auf einem FTP-Server abruft. „mdtm" steht für modification time (Änderungszeit) — sie entspricht direkt dem FTP-Protokollbefehl MDTM.

Sie ist besonders nützlich, wenn Sie Dateien synchronisieren, Änderungen erkennen oder entscheiden möchten, ob ein erneuter Download notwendig ist: Anstatt die gesamte Datei herunterzuladen, nur um zu prüfen, ob sie neuer als Ihre lokale Kopie ist, fragen Sie den Server zuerst nach dem Zeitstempel.

Die Funktion erwartet zwei Parameter:

1. ftp — der Verbindungsbezeichner, der von ftp_connect() zurückgegeben wird.
2. remote_file — der Pfad zur Datei auf dem Server.

Die Funktion gibt den Zeitpunkt der letzten Änderung als Unix-Timestamp (Sekunden seit 1970-01-01 UTC) zurück. Bei einem Fehler — die Datei existiert nicht, der Pfad verweist auf ein Verzeichnis oder die Verbindung ist ungültig — gibt sie -1 zurück.

ftp_mdtm() funktioniert nur mit regulären Dateien. Viele Server lehnen MDTM für Verzeichnisse ab, sodass der Aufruf für einen Ordner in der Regel -1 zurückgibt.

Syntax von ftp_mdtm()

ftp_mdtm(resource|FTP\Connection $ftp, string $remote_file): int

Der Typ resource wurde bis PHP 7 verwendet. Ab PHP 8.1 sind FTP-Verbindungen Objekte (FTP\Connection), sodass das erste Argument eine FTP\Connection-Instanz ist — Sie übergeben jedoch weiterhin das, was ftp_connect() zurückgegeben hat, sodass bestehender Code unverändert funktioniert.

Diese Funktion benötigt eine aktive FTP-Verbindung. Sie aktiviert den passiven Modus nicht automatisch; wenn Ihr Netzwerk hinter einer Firewall oder NAT liegt, rufen Sie ftp_pasv($ftp, true) nach dem Einloggen und vor dem Abrufen des Zeitstempels auf.

Grundlegende Verwendung

Um ftp_mdtm() zu verwenden, stellen Sie zunächst mit ftp_connect() eine Verbindung her und authentifizieren Sie sich mit ftp_login():

<?php

// Set up an FTP connection
$conn = ftp_connect('ftp.example.com');

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

// Enable passive mode (often required behind a firewall)
ftp_pasv($conn, true);

// Get the last modified time of the remote file (a Unix timestamp)
$last_modified = ftp_mdtm($conn, '/path/to/remote/file.txt');

// Close the FTP connection
ftp_close($conn);

Den Zeitstempel in ein lesbares Datum umwandeln

Da ftp_mdtm() einen rohen Unix-Timestamp zurückgibt, formatieren Sie diesen fast immer mit date(), bevor Sie ihn einem Benutzer anzeigen. Die Umwandlung ist reines PHP und läuft überall — kein FTP-Server erforderlich:

<?php

// Pretend ftp_mdtm() returned this timestamp
$last_modified = 1718000000;

echo "Raw timestamp: $last_modified\n";
echo "Formatted (UTC): " . gmdate('Y-m-d H:i:s', $last_modified) . " UTC\n";
echo "Year only: " . gmdate('Y', $last_modified) . "\n";

Ausgabe:

Raw timestamp: 1718000000
Formatted (UTC): 2024-06-10 06:13:20 UTC
Year only: 2024

MDTM gibt die Zeit in UTC zurück. Verwenden Sie gmdate() (oder setzen Sie die Zeitzone explizit), damit die angezeigte Zeit nicht unbemerkt durch die lokale Zeitzone Ihres Servers verschoben wird. Eine vollständige Liste der Formatzeichen finden Sie unter date().

Fehlerbehandlung in ftp_mdtm()

Da die Funktion bei einem Fehler -1 zurückgibt, prüfen Sie diesen Wert mit dem strikten Vergleichsoperator ===. Ein lockeres == würde auch false und andere falsy-Werte treffen und echte Ergebnisse verbergen:

<?php

$last_modified = ftp_mdtm($conn, '/path/to/remote/file.txt');

if ($last_modified === -1) {
    echo "Failed to retrieve the last modified time.\n";
} else {
    echo "Last modified: " . gmdate('Y-m-d H:i:s', $last_modified) . " UTC\n";
}

Häufiger Anwendungsfall: Nur herunterladen, wenn neuer

Der typische Grund für den Aufruf von ftp_mdtm() ist, den erneuten Download einer unveränderten Datei zu vermeiden. Vergleichen Sie den Remote-Zeitstempel mit der Änderungszeit Ihrer lokalen Datei:

<?php

$remote = '/path/to/remote/file.txt';
$local  = 'file.txt';

$remoteTime = ftp_mdtm($conn, $remote);

if ($remoteTime === -1) {
    echo "Could not read remote timestamp.\n";
} elseif (!file_exists($local) || $remoteTime > filemtime($local)) {
    echo "Remote file is newer — downloading.\n";
    ftp_get($conn, $local, $remote, FTP_BINARY);
} else {
    echo "Local copy is up to date — skipping download.\n";
}

Dieses Muster hält Spiegel und Backups effizient: Bytes werden nur übertragen, wenn die Kopie auf dem Server tatsächlich neuer ist.

Häufige Fallstricke

• Serverunterstützung variiert. MDTM ist kein Bestandteil des ursprünglichen FTP-Standards, daher implementieren einige ältere oder eingeschränkte Server ihn nicht und geben immer -1 zurück, selbst für vorhandene Dateien.
• Verzeichnisse geben -1 zurück. Verwenden Sie ftp_nlist(), um den Verzeichnisinhalt aufzulisten.
• Zeitzone. Zeitstempel sind in UTC; formatieren Sie mit gmdate(), um unerwartete Verschiebungen zu vermeiden.
• Benötigen Sie auch die Dateigröße? Kombinieren Sie die Funktion mit ftp_size().

Fazit

ftp_mdtm() ruft den Unix-Timestamp der letzten Änderung einer Datei auf einem FTP-Server ab und bildet damit den Grundbaustein für Änderungserkennung und inkrementelle Synchronisierung. Denken Sie daran, den Fehlerwert -1 mit === zu prüfen, das Ergebnis mit date() oder gmdate() zu formatieren und den passiven Modus zu aktivieren, wenn Ihr Netzwerk dies erfordert.

Übungen