stream_resolve_include_path — Funktion · PHP-Referenz

Signatur

stream_resolve_include_path(string $filename): string|false

Beschreibung

stream_resolve_include_path() sucht die angegebene Datei in allen Verzeichnissen, die in der PHP-Konfigurationsdirektive include_path hinterlegt sind, und gibt bei Erfolg den vollständigen absoluten Pfad zurück. Die Funktion verhält sich dabei exakt so, wie PHP intern beim Laden von Dateien via include oder require vorgeht.

Typischer Einsatz ist die Prüfung, ob eine Datei im Include-Pfad auffindbar ist, bevor sie tatsächlich eingebunden wird. So lassen sich aussagekräftigere Fehlermeldungen generieren oder alternative Implementierungen laden, wenn eine Datei fehlt. Im Gegensatz zu realpath() berücksichtigt diese Funktion den include_path, was sie für Autoloader und Framework-Bootstrapper besonders nützlich macht.

Die Funktion unterstützt auch Stream-Wrapper (z. B. phar://), sofern der jeweilige Wrapper die Pfadauflösung implementiert. Relative Pfade werden relativ zu den Einträgen im include_path geprüft, absolute Pfade werden direkt validiert.

Seit PHP 5.3.2 ist sie eine vollwertige Alternative zur manuellen Iteration über explode(PATH_SEPARATOR, get_include_path()) und deutlich robuster, da sie Betriebssystem-Besonderheiten wie abweichende Pfadtrennzeichen automatisch behandelt.

Parameter

Name	Typ	Default	Beschreibung
$filename Pflicht	string		Der Dateiname (relativ oder absolut), der im `include_path` gesucht werden soll. Stream-Wrapper-URLs wie `phar://archiv.phar/datei.php` sind ebenfalls erlaubt.

Rückgabewert

Typ

string|false

Beschreibung

Gibt den vollständigen, aufgelösten Pfad zur Datei als string zurück, wenn sie im include_path gefunden wurde. Ist die Datei nicht auffindbar oder nicht zugänglich, wird false zurückgegeben.

Beispiele

Datei im Include-Pfad suchen und einbinden

<?php
// Angenommen, include_path enthält '/var/www/lib'
// und dort liegt die Datei 'helper.php'

$resolved = stream_resolve_include_path('helper.php');

if ($resolved !== false) {
    echo 'Gefunden: ' . $resolved . PHP_EOL;
    require $resolved;
} else {
    throw new RuntimeException('helper.php wurde im include_path nicht gefunden.');
}

Gefunden: /var/www/lib/helper.php

Einfacher Autoloader mit stream_resolve_include_path

<?php
spl_autoload_register(function (string $className): void {
    // Klassennamen in Dateipfad umwandeln (PSR-0-ähnlich)
    $file = str_replace('\\', DIRECTORY_SEPARATOR, $className) . '.php';

    $resolved = stream_resolve_include_path($file);
    if ($resolved !== false) {
        require $resolved;
    } else {
        // Klasse konnte nicht geladen werden – PHP wirft selbst einen Fehler
        trigger_error(
            "Klasse '{$className}' nicht gefunden (Datei: {$file})",
            E_USER_WARNING
        );
    }
});

// Test: Klasse 'App\Controller\Home' → 'App/Controller/Home.php'
$obj = new App\Controller\Home();

Existenz einer Phar-Ressource prüfen

<?php
// Phar-Archiv in den include_path aufnehmen
set_include_path(get_include_path() . PATH_SEPARATOR . 'phar:///var/www/meine-bibliothek.phar');

$path = stream_resolve_include_path('src/Utils/StringHelper.php');

if ($path) {
    echo 'Phar-Ressource gefunden: ' . $path . PHP_EOL;
} else {
    echo 'Ressource nicht im Phar enthalten.' . PHP_EOL;
}

Phar-Ressource gefunden: phar:///var/www/meine-bibliothek.phar/src/Utils/StringHelper.php

// Wichtig · Fallstricke

Wichtig: Die Funktion gibt nur dann einen Pfad zurück, wenn die Datei auch tatsächlich lesbar ist. Sie folgt damit dem gleichen Verhalten wie include und require – eine nicht lesbare Datei wird als nicht gefunden behandelt.

Im Gegensatz zu file_exists() prüft stream_resolve_include_path() nicht nur den aktuellen Arbeitsordner, sondern den gesamten include_path. Eine Kombination beider Funktionen ist daher in den meisten Fällen nicht sinnvoll.

Achtung bei der Verwendung in Webanwendungen: Wenn der include_path unsichere oder vom Benutzer beeinflussbare Verzeichnisse enthält, kann ein manipulierter Dateiname zum unbeabsichtigten Laden von Dateien führen. Eingaben sollten stets validiert und bereinigt werden, bevor sie an diese Funktion übergeben werden.

Siehe auch

get_include_path set_include_path realpath file_exists spl_autoload_register include require