eio_symlink — Funktion · PHP-Referenz

Signatur

eio_symlink(string $path, string $new_path, int $pri = EIO_PRI_DEFAULT, callable $callback = NULL, mixed $data = NULL): resource

Beschreibung

eio_symlink() ist Teil der eio-Erweiterung und ermöglicht das asynchrone Anlegen eines symbolischen Links, ohne den PHP-Prozess zu blockieren. Dies ist besonders in ereignisgesteuerten Anwendungen (z. B. mit libevent oder libev) nützlich, wo blockierende I/O-Operationen vermieden werden sollen.

Der symbolische Link new_path wird so erstellt, dass er auf path zeigt – analog zum POSIX-Systemaufruf symlink(2). Der eigentliche Systemaufruf wird in einem Worker-Thread ausgeführt; nach Abschluss wird die angegebene Callback-Funktion aufgerufen.

Die Callback-Funktion erhält drei Argumente: $data (die optional übergebenen Benutzerdaten), den Ergebniscode (bei Erfolg 0, bei Fehler -1) sowie den errno-Wert. Über eio_get_last_error() oder eio_get_errno() können Fehlerdetails abgefragt werden.

Die Funktion setzt die installierte und aktivierte eio-Extension voraus und arbeitet nur korrekt zusammen mit einer Ereignisschleife, die eio_event_loop() oder Integration via eio_init() verwendet.

Parameter

Name	Typ	Default	Beschreibung
$path Pflicht	string		Der Zielpfad, auf den der symbolische Link verweisen soll.
$new_path Pflicht	string		Der Pfad, unter dem der neue symbolische Link angelegt wird.
$pri	int	EIO_PRI_DEFAULT	Priorität der Anfrage. Mögliche Werte: `EIO_PRI_DEFAULT`, `EIO_PRI_MIN`, `EIO_PRI_MAX`.
$callback	callable	NULL	Callback-Funktion, die nach Abschluss der Operation aufgerufen wird. Signatur: `function(mixed $data, int $result, resource $req): void`. `$result` ist `0` bei Erfolg, `-1` bei Fehler.
$data	mixed	NULL	Beliebige Benutzerdaten, die unverändert an die Callback-Funktion weitergereicht werden.

Rückgabewert

Typ

resource

Beschreibung

Gibt eine eio_req-Ressource zurück, die die ausstehende Anfrage repräsentiert, oder false bei einem Fehler beim Einreihen der Anfrage.

Beispiele

Symbolischen Link asynchron erstellen

<?php
// eio-Erweiterung muss installiert sein

$target  = '/var/www/html/uploads/original.txt';
$symlink = '/var/www/html/uploads/latest.txt';

eio_symlink(
    $target,
    $symlink,
    EIO_PRI_DEFAULT,
    function (mixed $data, int $result, $req): void {
        if ($result === 0) {
            echo "Symbolischer Link erfolgreich erstellt: {$data['link']}\n";
        } else {
            echo 'Fehler beim Erstellen des symbolischen Links: ' . eio_get_last_error($req) . "\n";
        }
    },
    ['link' => $symlink]
);

// Ereignisschleife starten, bis alle Anfragen abgearbeitet sind
eio_event_loop();

Symbolischer Link erfolgreich erstellt: /var/www/html/uploads/latest.txt

Fehlerbehandlung bei bereits vorhandenem Link

<?php
$target  = '/tmp/zieldatei.txt';
$symlink = '/tmp/mein_link.txt';

// Sicherstellen, dass die Zieldatei existiert
file_put_contents($target, 'Inhalt');

// Ersten Link erstellen
eio_symlink(
    $target,
    $symlink,
    EIO_PRI_DEFAULT,
    function (mixed $data, int $result, $req): void {
        echo 'Erster Versuch: ' . ($result === 0 ? 'Erfolg' : 'Fehler – ' . eio_get_last_error($req)) . "\n";
    }
);
eio_event_loop();

// Zweiten Versuch mit demselben Link-Pfad (schlägt fehl, da bereits vorhanden)
eio_symlink(
    $target,
    $symlink,
    EIO_PRI_DEFAULT,
    function (mixed $data, int $result, $req): void {
        echo 'Zweiter Versuch: ' . ($result === 0 ? 'Erfolg' : 'Fehler – ' . eio_get_last_error($req)) . "\n";
    }
);
eio_event_loop();

// Aufräumen
unlink($symlink);
unlink($target);

Erster Versuch: Erfolg Zweiter Versuch: Fehler – File exists

// Wichtig · Fallstricke

Achtung: Die eio-Erweiterung ist standardmäßig nicht in PHP enthalten und muss separat über PECL installiert werden (pecl install eio). Ohne eine laufende Ereignisschleife (z. B. eio_event_loop()) wird der Callback nie ausgeführt.

Sicherheit: Beim Erstellen symbolischer Links in öffentlich zugänglichen Verzeichnissen besteht das Risiko von Symlink-Race-Condition-Angriffen (TOCTOU). Achte darauf, Zielpfade zu validieren und keine nutzergesteuerten Pfade ungeprüft zu verwenden.

Unter Windows wird diese Funktion möglicherweise nicht unterstützt, da libeio intern POSIX-Systemaufrufe verwendet.

Siehe auch

eio_link eio_unlink eio_rename eio_readlink eio_event_loop symlink