ftp_site()

Die PHP-Funktion ftp_site() verstehen

Die Funktion ftp_site() ist eine eingebaute PHP-Funktion, die einen SITE-Befehl an einen FTP-Server sendet. SITE ist ein universeller FTP-Befehl für Anweisungen, die außerhalb des Standard-FTP-Protokolls liegen – Dinge, die jeder Serverhersteller auf seine eigene Weise implementiert, wie etwa das Ändern von Dateirechten, das Anpassen von Leerlauf-Timeouts oder das Ausführen serverspezifischer Wartungsaufgaben.

Da die Bedeutung eines SITE-Befehls vollständig vom Remote-Server definiert wird, ist ftp_site() der Ausweg, wenn keine dedizierte PHP-FTP-Funktion für das existiert, was man benötigt. Dieser Artikel erklärt, was die Funktion tut, wann man sie verwenden sollte (und wann nicht), und wie man ihr Ergebnis sicher verarbeitet.

Um damit zu arbeiten, öffnet man zunächst eine Verbindung mit ftp_connect() und authentifiziert sich mit ftp_login(). Eine Übersicht der gesamten Funktionsfamilie bietet der PHP-FTP-Überblick.

Was ist ftp_site()?

Die Funktion nimmt zwei Parameter entgegen:

1. ftp — Die FTP-Verbindung, die von ftp_connect() (oder ftp_ssl_connect()) zurückgegeben wird.
2. command — Der rohe SITE-Befehlsstring, der gesendet werden soll, ohne das vorangestellte Schlüsselwort SITE (PHP fügt es automatisch hinzu).

Die Funktion gibt true zurück, wenn der Server den Befehl akzeptiert hat, und false bei einem Fehler. Ein true-Ergebnis bedeutet nur, dass der Server den Befehl akzeptiert hat – es garantiert nicht, dass die zugrunde liegende Aktion (z. B. die Berechtigungsänderung) erfolgreich war, da das SITE-Verhalten vom Server definiert wird.

Syntax von ftp_site()

Die Syntax der Funktion ftp_site() lautet wie folgt:

Syntax von ftp_site()

ftp_site(FTP\Connection $ftp, string $command): bool

Ab PHP 8.1 ist das erste Argument ein FTP\Connection-Objekt (in älteren Versionen war es eine Resource). Das Argument command ist die zu sendende SITE-Anweisung – zum Beispiel CHMOD 644 file.txt. Es wird nur der Teil nach SITE übergeben; PHP stellt das Schlüsselwort automatisch voran.

Verwendung von ftp_site()

Um die Funktion ftp_site() zu verwenden, muss zunächst eine Verbindung zum FTP-Server über die Funktion ftp_connect() hergestellt werden. Hier ist ein Beispiel:

Verwendung von ftp_site()

<?php

// Set up an FTP connection
$conn = @ftp_connect('ftp.example.com');
if (!$conn) {
    die('Could not connect to server.');
}

// Login with your FTP credentials
if (!ftp_login($conn, 'username', 'password')) {
    die('Login failed.');
}

// Send the SITE command
ftp_site($conn, 'CHMOD 755 /public_html/index.php');

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

In diesem Beispiel verbinden wir uns mit ftp_connect(), authentifizieren uns mit ftp_login(), senden SITE CHMOD 755, um die Berechtigungen von index.php zu ändern, und schließen schließlich die Verbindung mit ftp_close().

Hinweis: SITE-Befehle sind serverspezifisch. SITE CHMOD wird nicht von allen FTP-Servern universell unterstützt. Für standardmäßige Dateirechteänderungen bevorzuge die dedizierte Funktion ftp_chmod(), die portabel ist und den neuen Berechtigungswert zurückgibt. Verwende ftp_site() nur für Aktionen, für die es keine dedizierte FTP-Funktion gibt.

Häufige SITE-Befehle

Die genaue Menge der unterstützten Befehle hängt von der Serversoftware ab (ProFTPD, vsftpd, Pure-FTPd usw.), aber einige sind weit verbreitet:

Im Zweifelsfall führe SITE HELP aus, um herauszufinden, was ein bestimmter Server akzeptiert:

Unterstützte SITE-Befehle ermitteln

<?php

$conn = ftp_connect('ftp.example.com');
ftp_login($conn, 'username', 'password');

if (ftp_site($conn, 'HELP')) {
    echo "Server accepted the SITE HELP command.\n";
}

ftp_close($conn);

Fehlerbehandlung in ftp_site()

Es ist wichtig, Fehler bei der Verwendung der Funktion ftp_site() korrekt zu behandeln. Wenn die Funktion false zurückgibt, bedeutet das, dass die Operation fehlgeschlagen ist. Hier ist ein Beispiel zur Fehlerbehandlung:

Fehlerbehandlung in ftp_site()

<?php

if (!ftp_site($conn, 'CHMOD 755 /public_html/index.php')) {
    echo "Failed to send SITE command.\n";
}

ftp_close($conn);

Durch Überprüfung des Rückgabewerts vermeidet man, stillschweigend nach einem vom Server abgelehnten Befehl fortzufahren. Zu beachten ist, dass ftp_site() sowohl bei einer schlechten Verbindung als auch wenn der Server den Befehl schlicht nicht erkennt false zurückgibt – ein false-Ergebnis ist also das Signal, auf eine dedizierte Funktion oder einen anderen Ansatz zurückzugreifen.

ftp_site() vs. ftp_raw() und ftp_exec()

ftp_site() ist eng mit zwei anderen "rohe Anweisung senden"-Funktionen verwandt, und es hilft zu wissen, wann man welche wählen sollte:

• ftp_site() — sendet einen einzelnen SITE-Befehl und gibt einen boolean-Wert zurück. Verwende sie für serverspezifische Aktionen wie CHMOD oder UMASK.
• ftp_raw() — sendet jeden beliebigen rohen FTP-Befehl (nicht nur SITE) und gibt die vollständige Serverantwort als array zurück, sodass man den Statuscode selbst auslesen kann. Verwende sie, wenn die Antwort ausgewertet werden soll.
• ftp_exec() — führt ein Programm auf dem Server via SITE EXEC aus, sofern unterstützt. Verwende sie nur auf Servern, die man kontrolliert und denen man vertraut.

Für alltägliche Operationen (Hochladen, Herunterladen, Auflisten, Umbenennen) bevorzuge die zweckgebundenen Funktionen aus dem PHP-FTP-Überblick; sie sind portabler als selbst erstellte SITE-Befehle.

Fazit

Die Funktion ftp_site() ermöglicht das Senden serverspezifischer SITE-Befehle, wenn keine dedizierte PHP-FTP-Funktion passt. Den Rückgabewert immer prüfen, bedenken, dass ein erfolgreiches Senden nicht dasselbe ist wie eine erfolgreiche Aktion, und portable Funktionen wie ftp_chmod() bevorzugen, wann immer eine solche existiert.

Übung