Uri\WhatWg\Url — Klasse · PHP-Referenz

Signatur

class Uri\WhatWg\Url

Beschreibung

Die Klasse Uri\WhatWg\Url implementiert den WHATWG-URL-Standard direkt in PHP. Sie ermöglicht das Parsen, Validieren und Inspizieren von URLs in einer Weise, die exakt dem Verhalten moderner Webbrowser entspricht – einschließlich aller Sonderfälle bei der Normalisierung, Prozentcodierung und Auflösung relativer URLs.

Im Gegensatz zur klassischen PHP-Funktion parse_url() liefert diese Klasse eine vollständig normalisierte URL-Darstellung. Ungültige URLs führen zu einer Uri\WhatWg\InvalidUrlException, sodass Fehler früh erkannt werden. Die Klasse eignet sich besonders für Webanwendungen, die auf Interoperabilität mit JavaScript-Umgebungen oder Browser-Verhalten angewiesen sind.

Alle Eigenschaften der Klasse sind schreibgeschützt (readonly) und spiegeln die einzelnen Bestandteile der URL wider: scheme, username, password, host, port, path, query und fragment. Über toAsciiString() bzw. toUnicodeString() lässt sich die serialisierte URL abrufen.

Die Klasse ist als unveränderliches Wertobjekt konzipiert: Jede Modifikation einer Komponente liefert eine neue Instanz zurück (withScheme(), withHost() usw.), was thread-sicheres und nebenwirkungsfreies Arbeiten ermöglicht.

Parameter

Name	Typ	Default	Beschreibung
$url Pflicht	string		Die zu parsende URL als Zeichenkette. Muss eine gültige absolute URL gemäß WHATWG-Standard sein, andernfalls wird eine `Uri\WhatWg\InvalidUrlException` geworfen.
$base	string\|Uri\WhatWg\Url\|null	null	Optionale Basis-URL zur Auflösung relativer URLs. Wird `null` übergeben und `url` ist relativ, wird eine Ausnahme geworfen.

Beispiele

Einfaches Parsen und Komponentenzugriff

<?php
use Uri\WhatWg\Url;

$url = new Url('https://user:pass@example.com:8080/pfad?suche=1#abschnitt');

echo $url->scheme;    // https
echo $url->host;      // example.com
echo $url->port;      // 8080
echo $url->path;      // /pfad
echo $url->query;     // suche=1
echo $url->fragment;  // abschnitt
echo $url->toAsciiString();
// https://user:pass@example.com:8080/pfad?suche=1#abschnitt

https example.com 8080 /pfad suche=1 abschnitt https://user:pass@example.com:8080/pfad?suche=1#abschnitt

Auflösung einer relativen URL anhand einer Basis-URL

<?php
use Uri\WhatWg\Url;

$basis = new Url('https://example.com/app/index.html');
$relativ = new Url('../bilder/logo.png', $basis);

echo $relativ->toAsciiString();
// https://example.com/bilder/logo.png

https://example.com/bilder/logo.png

Unveränderliche Modifikation einer URL-Komponente

<?php
use Uri\WhatWg\Url;

$original = new Url('http://example.com/seite');
$sicher   = $original->withScheme('https');

echo $original->toAsciiString(); // http://example.com/seite
echo $sicher->toAsciiString();   // https://example.com/seite

http://example.com/seite https://example.com/seite

Fehlerbehandlung bei ungültiger URL

<?php
use Uri\WhatWg\Url;
use Uri\WhatWg\InvalidUrlException;

try {
    $url = new Url('keine gültige url');
} catch (InvalidUrlException $e) {
    echo 'Ungültige URL: ' . $e->getMessage();
}

Ungültige URL: ...

// Wichtig · Fallstricke

Sicherheitshinweis: Die WHATWG-konforme Normalisierung kann dazu führen, dass URLs, die optisch identisch aussehen, intern unterschiedlich behandelt werden (z. B. durch unterschiedliche Unicode-Normalisierungsformen im Host). Vergleiche sollten daher immer über toAsciiString() erfolgen und nicht über Rohzeichenketten.

Unterschied zu parse_url(): parse_url() folgt keinem definierten Standard und verhält sich bei Randfällen anders als Browser. Für browserkompatibles URL-Handling sollte stets Uri\WhatWg\Url bevorzugt werden.

Die Klasse befindet sich im Namespace Uri\WhatWg, der als PHP-Extension (ext-uri) seit PHP 8.4 im Core enthalten ist. Für ältere PHP-Versionen gibt es keine offizielle Portierung.

Siehe auch

Uri\WhatWg\InvalidUrlException parse_url http_build_url Uri\WhatWg\UrlSearchParams