Signatur
Beschreibung
Die Klasse Uri\Rfc3986\Uri wurde in PHP 8.4 eingeführt und modelliert eine URI (Uniform Resource Identifier) strikt nach dem Standard RFC 3986. Sie ist final und unveränderlich (immutable): Einmal erzeugte Instanzen können nicht mehr verändert werden. Methoden, die eine modifizierte URI zurückgeben, liefern stets eine neue Instanz.
Die Klasse erlaubt das Parsen, Inspizieren und komponentenweise Lesen einer URI. Über die implementierten Interfaces Uri\UriInterface und Stringable lässt sich die URI sowohl typsicher verarbeiten als auch direkt als String verwenden. Falsch geformte URIs führen beim Parsen zu einer Uri\InvalidUriException.
Typische Einsatzgebiete sind die Verarbeitung eingehender oder ausgehender URLs in HTTP-Clients, API-Gateways, Routing-Systemen sowie überall dort, wo eine zuverlässige, standardkonforme URI-Zerlegung benötigt wird. Im Gegensatz zur älteren Funktion parse_url() bietet die Klasse ein objektorientiertes, fehlerbehandlungsfähiges Interface.
Alle Getter-Methoden geben null zurück, wenn die jeweilige Komponente in der URI nicht vorhanden ist – außer getPath(), das stets einen String (ggf. leer) liefert.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $uri Pflicht | string | Die zu parsende URI als Zeichenkette, z. B. "https://user:pass@example.com:8080/path?q=1#sec". Muss syntaktisch gültig nach RFC 3986 sein, sonst wird eine Uri\InvalidUriException geworfen. |
Beispiele
URI parsen und Komponenten auslesen
<?php
use Uri\Rfc3986\Uri;
$uri = new Uri('https://user:secret@example.com:8080/api/v1/resource?filter=active&page=2#results');
echo $uri->getScheme() . PHP_EOL; // https
echo $uri->getUser() . PHP_EOL; // user
echo $uri->getPassword() . PHP_EOL; // secret
echo $uri->getHost() . PHP_EOL; // example.com
echo $uri->getPort() . PHP_EOL; // 8080
echo $uri->getPath() . PHP_EOL; // /api/v1/resource
echo $uri->getQuery() . PHP_EOL; // filter=active&page=2
echo $uri->getFragment() . PHP_EOL; // results
// Als String nutzen (Stringable)
echo (string) $uri . PHP_EOL;Fehlerbehandlung bei ungültiger URI
<?php
use Uri\Rfc3986\Uri;
use Uri\InvalidUriException;
$input = "://ungültige uri!";
try {
$uri = new Uri($input);
echo "Gültig: " . $uri->getHost();
} catch (InvalidUriException $e) {
echo "Ungültige URI: " . $e->getMessage() . PHP_EOL;
}Relativen Pfad und fehlende Komponenten prüfen
<?php
use Uri\Rfc3986\Uri;
$uri = new Uri('/nur/ein/pfad?suche=php');
var_dump($uri->getScheme()); // NULL
var_dump($uri->getHost()); // NULL
var_dump($uri->getPort()); // NULL
var_dump($uri->getPath()); // string("/nur/ein/pfad")
var_dump($uri->getQuery()); // string("suche=php")
var_dump($uri->getFragment()); // NULL// Wichtig · Fallstricke
Sicherheitshinweis: Die Klasse prüft nur die syntaktische Gültigkeit nach RFC 3986, nicht die semantische Sicherheit der URI. Hosts, Pfade und Query-Parameter müssen vor der Verwendung in SQL-Abfragen, Shell-Befehlen oder HTML-Ausgaben weiterhin separat escaped bzw. validiert werden.
Unveränderlichkeit: Da die Klasse final und immutable ist, können keine Komponenten nachträglich gesetzt werden. Soll eine veränderte URI erzeugt werden, muss eine neue Instanz mit dem gewünschten String erstellt werden.
Abgrenzung zu parse_url(): Im Gegensatz zu parse_url() wirft Uri\Rfc3986\Uri bei fehlerhafter Eingabe eine typisierte Exception, anstatt false oder inkonsistente Arrays zurückzugeben. Dies erleichtert eine robuste Fehlerbehandlung erheblich.