ssh2_sftp_realpath — Funktion · PHP-Referenz

Signatur

ssh2_sftp_realpath(resource $sftp, string $filename): string|false

Beschreibung

ssh2_sftp_realpath() nimmt einen beliebigen Pfadstring (relativ, mit Symlinks oder ./..-Anteilen) und gibt den vom SFTP-Server aufgelösten, absoluten Pfad zurück. Die Funktion ist das SFTP-Äquivalent zur lokalen PHP-Funktion realpath(), arbeitet jedoch vollständig auf dem entfernten Dateisystem.

Typische Einsatzbereiche sind die Auflösung von Home-Verzeichnissen (z. B. ~ oder .), die Kanonisierung von Pfaden vor weiteren SFTP-Operationen sowie die Überprüfung, ob ein bestimmter Pfad auf dem Server tatsächlich existiert und erreichbar ist.

Die Funktion benötigt eine gültige SFTP-Ressource, die zuvor mit ssh2_sftp() aus einer aktiven SSH2-Verbindung erzeugt wurde. Schlägt die Auflösung fehl – etwa weil der Pfad nicht existiert oder der Benutzer keine Leserechte hat –, wird false zurückgegeben.

Hinweis: Diese Funktion ist Teil der PECL-Erweiterung ssh2 und muss separat installiert werden. Sie steht nicht in der PHP-Standardinstallation zur Verfügung.

Parameter

Name	Typ	Default	Beschreibung
$sftp Pflicht	resource		Eine SFTP-Ressource, die mit `ssh2_sftp()` aus einer aktiven SSH2-Verbindung erzeugt wurde.
$filename Pflicht	string		Der aufzulösende Pfad auf dem entfernten Server. Kann relativ, absolut oder mit Symlinks versehen sein (z. B. `.`, `..`, `~` oder `/var/www/../html`).

Rückgabewert

Typ

string|false

Beschreibung

Gibt den absoluten, kanonischen Pfad als String zurück. Im Fehlerfall (Pfad nicht vorhanden, fehlende Rechte, Verbindungsfehler) wird false zurückgegeben.

Beispiele

Aktuelles Arbeitsverzeichnis des SFTP-Nutzers auflösen

<?php
// SSH-Verbindung herstellen
$connection = ssh2_connect('sftp.example.com', 22);
ssh2_auth_password($connection, 'benutzer', 'geheimesPasswort');

// SFTP-Subsystem starten
$sftp = ssh2_sftp($connection);

// Aktuelles Verzeichnis (.) auflösen
$realpath = ssh2_sftp_realpath($sftp, '.');

if ($realpath !== false) {
    echo "Absoluter Pfad: " . $realpath . PHP_EOL;
} else {
    echo "Pfad konnte nicht aufgelöst werden." . PHP_EOL;
}
?>

Absoluter Pfad: /home/benutzer

Symlink auf dem entfernten Server auflösen

<?php
$connection = ssh2_connect('sftp.example.com', 22);
ssh2_auth_password($connection, 'benutzer', 'geheimesPasswort');

$sftp = ssh2_sftp($connection);

// Relativen Pfad mit Symlink auflösen
$path = '/var/www/html/../logs/app/../current';
$realpath = ssh2_sftp_realpath($sftp, $path);

if ($realpath !== false) {
    echo "Kanonischer Pfad: " . $realpath . PHP_EOL;
} else {
    echo "Pfad existiert nicht oder ist nicht erreichbar." . PHP_EOL;
}

// Sicherer Dateidownload mit aufgelöstem Pfad
if ($realpath !== false) {
    $inhalt = file_get_contents("ssh2.sftp://{$sftp}{$realpath}/access.log");
    echo $inhalt;
}
?>

Kanonischer Pfad: /var/www/current

// Wichtig · Fallstricke

Sicherheitshinweis: Bevor Benutzereingaben als Pfadargument an ssh2_sftp_realpath() übergeben werden, sollten diese sorgfältig validiert werden. Obwohl die Funktion den Pfad auf dem Server auflöst, ist Path-Traversal-Angriffe (z. B. ../../etc/passwd) entgegenzuwirken, indem der zurückgegebene absolute Pfad gegen ein erlaubtes Basisverzeichnis geprüft wird.

Die Funktion erfordert die PECL-Erweiterung ssh2 (libssh2). Diese kann über pecl install ssh2 installiert werden und muss in der php.ini mit extension=ssh2 aktiviert sein.

Nicht alle SFTP-Server-Implementierungen unterstützen den realpath-Befehl vollständig. In solchen Fällen kann die Funktion false zurückgeben, auch wenn der Pfad prinzipiell existiert.

Siehe auch

ssh2_sftp ssh2_connect ssh2_sftp_stat ssh2_sftp_symlink realpath