eio_realpath — Funktion · PHP-Referenz

Signatur

eio_realpath(string $path, int $pri, callable $callback, mixed $data = null): resource

Beschreibung

eio_realpath() ist Teil der eio-Erweiterung, die asynchrone POSIX-I/O-Operationen für PHP bereitstellt. Die Funktion löst einen relativen oder symbolischen Pfad in den vollständigen, kanonischen absoluten Pfad auf, ohne den PHP-Prozess dabei zu blockieren – das Pendant zur synchronen Funktion realpath().

Da die Operation asynchron abläuft, wird das Ergebnis nicht sofort zurückgegeben, sondern über eine Callback-Funktion geliefert, sobald das Betriebssystem die Anfrage bearbeitet hat. Der Rückgabewert der Callback-Funktion enthält bei Erfolg den aufgelösten Pfad als String.

Typische Einsatzgebiete sind Hochlast-Anwendungen, Dateiserver oder Event-Loop-basierte Architekturen (z. B. mit libeio oder ReactPHP), bei denen blockierende Systemaufrufe die Performance negativ beeinflussen würden. eio_realpath() eignet sich immer dann, wenn Pfadauflösungen auf Datei-System-Ebene in einem nicht-blockierenden Kontext durchgeführt werden müssen.

Beachte, dass die eio-Erweiterung explizit installiert und aktiviert sein muss (PECL-Paket eio) und dass die Callback-Verarbeitung den Event-Loop (z. B. via eio_event_loop()) voraussetzt.

Parameter

Name	Typ	Default	Beschreibung
$path Pflicht	string		Der aufzulösende Dateipfad. Kann relativ, absolut oder ein symbolischer Link sein. Der Pfad muss für den laufenden PHP-Prozess zugänglich sein.
$pri Pflicht	int		Priorität der Anfrage. Mögliche Werte: `EIO_PRI_DEFAULT`, `EIO_PRI_MIN`, `EIO_PRI_MAX`. Steuert, in welcher Reihenfolge ausstehende eio-Anfragen abgearbeitet werden.
$callback Pflicht	callable		Callback-Funktion, die nach Abschluss der Operation aufgerufen wird. Signatur: `callback(mixed $data, mixed $result): void`. `$result` enthält bei Erfolg den aufgelösten absoluten Pfad als String, bei Fehler `false` oder `-1`.
$data	mixed	null	Optionale benutzerdefinierte Daten, die unverändert an die Callback-Funktion als erstes Argument weitergereicht werden. Nützlich zur Übergabe von Kontext-Informationen.

Rückgabewert

Typ

resource

Beschreibung

Gibt bei Erfolg eine eio-Request-Ressource zurück, mit der die asynchrone Anfrage z. B. über eio_cancel() abgebrochen werden kann. Bei Fehler wird false zurückgegeben.

Beispiele

Einfache asynchrone Pfadauflösung

<?php
// eio-Erweiterung muss installiert sein (pecl install eio)

$path = '/var/www/../www/html';

$req = eio_realpath(
    $path,
    EIO_PRI_DEFAULT,
    function (mixed $data, mixed $result): void {
        if ($result === false || $result === -1) {
            echo "Fehler beim Auflösen des Pfads.\n";
        } else {
            echo "Kanonischer Pfad: " . $result . "\n";
        }
    },
    null
);

eio_event_loop();

Kanonischer Pfad: /var/www/html

Pfadauflösung mit Kontextdaten im Callback

<?php
// Übergabe von Kontext-Daten über den $data-Parameter

$paths = [
    '/tmp/symlink_to_somewhere',
    '/etc/../etc/hosts',
];

foreach ($paths as $index => $path) {
    eio_realpath(
        $path,
        EIO_PRI_DEFAULT,
        function (mixed $data, mixed $result) {
            $label = $data['label'];
            if ($result === false || $result === -1) {
                echo "[$label] Auflösung fehlgeschlagen.\n";
            } else {
                echo "[$label] Aufgelöster Pfad: $result\n";
            }
        },
        ['label' => "Pfad #$index ($path)"]
    );
}

eio_event_loop();

[Pfad #0 (/tmp/symlink_to_somewhere)] Aufgelöster Pfad: /srv/zieldirectory [Pfad #1 (/etc/../etc/hosts)] Aufgelöster Pfad: /etc/hosts

// Wichtig · Fallstricke

Voraussetzung: Die eio-Erweiterung ist kein Bestandteil der PHP-Standardinstallation und muss über PECL (pecl install eio) nachinstalliert werden. Sie ist nur auf POSIX-kompatiblen Systemen (Linux, macOS) verfügbar – nicht unter Windows.

Event-Loop: Ohne Aufruf von eio_event_loop() oder eine äquivalente Integration (z. B. über libevent oder libuv) wird der Callback niemals ausgeführt. In produktiven Anwendungen sollte der Event-Loop sauber in die Anwendungsarchitektur integriert sein.

Fehlerbehandlung: Im Callback-Ergebnis sollte stets auf false und -1 geprüft werden. Fehler können auftreten, wenn der Pfad nicht existiert, nicht zugänglich ist oder ein symbolischer Link in einer Schleife endet.

Sicherheit: Wie bei realpath() gilt: Niemals den aufgelösten Pfad ungefiltert für Dateioperationen verwenden, wenn der ursprüngliche Pfad aus Benutzereingaben stammt. Path-Traversal-Angriffe sind auch hier möglich, wenn der kanonische Pfad nicht gegen ein erlaubtes Basisverzeichnis validiert wird.

Siehe auch

realpath eio_event_loop eio_cancel eio_stat eio_open