Signatur
Beschreibung
ssh2_sftp_symlink() erzeugt auf einem entfernten Server über eine bestehende SFTP-Verbindung einen symbolischen Link (Symlink). Die Funktion gehört zur SSH2-Erweiterung (PECL) und erfordert eine zuvor mit ssh2_connect() und ssh2_sftp() aufgebaute SFTP-Session.
Der Parameter $target gibt das Ziel an, auf das der symbolische Link zeigen soll, während $link den Pfad und Namen des zu erstellenden Links auf dem entfernten System definiert. Beide Pfade werden relativ zum Arbeitsverzeichnis der SFTP-Session interpretiert, sofern keine absoluten Pfade angegeben werden.
Diese Funktion ist besonders nützlich bei der Automatisierung von Deploy-Prozessen, bei denen auf dem Zielserver Symlinks gesetzt werden müssen, zum Beispiel um eine neue Release-Version als aktuelle Version zu verlinken, ohne direkten Shell-Zugriff zu haben.
Zu beachten ist, dass die Funktion zur PECL-Erweiterung ssh2 gehört und nicht standardmäßig in PHP enthalten ist. Sie muss separat installiert werden.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $sftp Pflicht | resource | Eine SFTP-Ressource, die zuvor mit ssh2_sftp() erstellt wurde. |
|
| $target Pflicht | string | Der Pfad zur Zieldatei oder zum Zielverzeichnis, auf die der symbolische Link zeigen soll. Kann absolut oder relativ sein. | |
| $link Pflicht | string | Der Pfad und Name des symbolischen Links, der auf dem entfernten Server erstellt werden soll. |
Rückgabewert
true zurück, wenn der symbolische Link erfolgreich erstellt wurde, andernfalls false. Im Fehlerfall (z. B. fehlende Berechtigungen, ungültige Pfade) wird false zurückgegeben und eine Warnung ausgegeben.Beispiele
Symbolischen Link nach einem Deployment erstellen
<?php
// SSH-Verbindung aufbauen
$connection = ssh2_connect('example.com', 22);
ssh2_auth_password($connection, 'benutzer', 'geheimesPasswort');
// SFTP-Subsystem initialisieren
$sftp = ssh2_sftp($connection);
// Neues Release verlinken: /var/www/current -> /var/www/releases/v2.5.0
$target = '/var/www/releases/v2.5.0';
$link = '/var/www/current';
if (ssh2_sftp_symlink($sftp, $target, $link)) {
echo "Symbolischer Link erfolgreich erstellt: {$link} -> {$target}";
} else {
echo "Fehler beim Erstellen des symbolischen Links.";
}
?>Relativen Symlink im SFTP-Stream-Kontext erstellen
<?php
$connection = ssh2_connect('example.com', 22);
ssh2_auth_pubkey_file(
$connection,
'benutzer',
'/home/user/.ssh/id_rsa.pub',
'/home/user/.ssh/id_rsa'
);
$sftp = ssh2_sftp($connection);
// Relativer Symlink: logs -> ../shared/logs
$ziel = '../shared/logs';
$link = '/var/www/releases/v2.5.0/logs';
$erfolg = ssh2_sftp_symlink($sftp, $ziel, $link);
if ($erfolg) {
echo "Relativer Symlink wurde angelegt.";
} else {
echo "Symlink konnte nicht erstellt werden – Berechtigungen prüfen!";
}
?>// Wichtig · Fallstricke
Sicherheitshinweis: Stellen Sie sicher, dass der Zielpfad ($target) und der Link-Pfad ($link) aus vertrauenswürdigen Quellen stammen. Ein durch Benutzereingaben manipulierter Pfad könnte dazu führen, dass Symlinks auf sensible Dateien zeigen (Symlink-Angriffe). Pfade sollten grundsätzlich validiert und canonisiert werden.
PECL-Abhängigkeit: Die Funktion ist Teil der PECL-Erweiterung ssh2 und ist nicht standardmäßig in PHP verfügbar. Die Erweiterung muss über PECL oder das Paketmanagement des Betriebssystems installiert werden (pecl install ssh2 bzw. apt install php-ssh2).
Falls der angegebene Link-Pfad bereits existiert, schlägt die Funktion fehl. Ein vorhandener Symlink oder eine Datei unter diesem Pfad muss zunächst entfernt werden.