Arbeiten mit URLs

Die Klassen Url, UrlImmutable und UrlScript erleichtern das Erzeugen, Parsen und Verändern von URLs.

→ Installation und Anforderungen

Url

Die Klasse Nette\Http\Url erlaubt die bequeme Arbeit mit URLs und ihren einzelnen Bestandteilen, wie dieses Diagramm zeigt:

scheme  user  password  host   port    path        query  fragment
  |      |      |        |      |       |            |       |
/--\   /--\ /------\ /-------\ /--\/----------\ /--------\ /----\
http://john:xyz%2A12@nette.org:8080/en/download?name=param#footer
\______\__________________________/
    |               |
 hostUrl        authority

Das Erzeugen von URLs ist intuitiv:

use Nette\Http\Url;

$url = new Url;
$url->setScheme('https')
	->setHost('localhost')
	->setPath('/edit')
	->setQueryParameter('foo', 'bar');

echo $url; // 'https://localhost/edit?foo=bar'

Sie können eine URL auch parsen und dann verändern:

$url = new Url(
	'http://john:xyz%2A12@nette.org:8080/en/download?name=param#footer',
);

Die Klasse Url implementiert das Interface JsonSerializable und hat eine Methode __toString(), das Objekt lässt sich also ausgeben oder in Daten verwenden, die an json_encode() übergeben werden.

echo $url;
echo json_encode([$url]);

URL-Komponenten

Zum Auslesen oder Ändern der einzelnen URL-Komponenten stehen folgende Methoden zur Verfügung:

Die Methoden getUser(), getPassword(), setUser() und setPassword() sind veraltet, weil vom Einbetten von Zugangsdaten direkt in die URL abgeraten wird.

Achtung: Wenn Sie mit einer URL arbeiten, die Sie aus einem HTTP-Request erhalten haben, denken Sie daran, dass sie das Fragment nicht enthält, denn der Browser sendet es nicht an den Server.

Mit den einzelnen Query-Parametern können wir außerdem so arbeiten:

getDomain (int $level = 2): string

Gibt den rechten oder linken Teil des Hosts zurück. So funktioniert es, wenn der Host www.nette.org ist:

isEqual (string|Url $url): bool

Prüft, ob zwei URLs identisch sind.

$url->isEqual('https://nette.org');

canonicalize()

Wandelt die URL in die kanonische Form um. Dabei wird der Hostname in Kleinbuchstaben umgewandelt und der Pfad normalisiert (Percent-Encoding und Entfernen überflüssiger Zeichen). Der Query-String bleibt unverändert.

Url::isAbsolute (string $url): bool

Prüft, ob eine URL absolut ist. Eine URL gilt als absolut, wenn sie mit einem Schema (z. B. http, https, ftp) gefolgt von einem Doppelpunkt beginnt.

Url::isAbsolute('https://nette.org');    // true
Url::isAbsolute('//nette.org');          // false

Url::removeDotSegments (string $path): string

Normalisiert einen URL-Pfad, indem die speziellen Segmente . und .. entfernt werden. Diese Methode entfernt überflüssige Pfadelemente auf dieselbe Weise wie Webbrowser.

Url::removeDotSegments('/path/../subtree/./file.txt');  // '/subtree/file.txt'
Url::removeDotSegments('/../foo/./bar');                // '/foo/bar'
Url::removeDotSegments('./today/../file.txt');          // 'file.txt'

UrlImmutable

Die Klasse Nette\Http\UrlImmutable ist eine unveränderliche Alternative zur Klasse Url (ähnlich wie DateTimeImmutable in PHP eine unveränderliche Alternative zu DateTime ist). Statt Settern hat sie “Wither”, die das Objekt nicht verändern, sondern neue Instanzen mit dem geänderten Wert zurückgeben:

use Nette\Http\UrlImmutable;

$url = new UrlImmutable(
	'https://nette.org:8080/en/download?name=param#footer',
);

$newUrl = $url
	->withHost('example.com')
	->withPath('/en/')
	->withQueryParameter('name', 'value');

echo $newUrl; // 'https://example.com:8080/en/?name=value#footer'

Die Klasse UrlImmutable implementiert das Interface JsonSerializable und hat eine Methode __toString(), das Objekt lässt sich also ausgeben oder in Daten verwenden, die an json_encode() übergeben werden.

echo $url;
echo json_encode([$url]);

URL-Komponenten

Zum Auslesen oder Ändern der einzelnen URL-Komponenten stehen folgende Methoden zur Verfügung:

Die Methoden getUser(), getPassword(), withUser(), withPassword() und withoutUserInfo() sind veraltet, weil vom Einbetten von Zugangsdaten direkt in die URL abgeraten wird.

Mit den einzelnen Query-Parametern können wir außerdem so arbeiten:

getDomain (int $level = 2): string

Gibt den rechten oder linken Teil des Hosts zurück. So funktioniert es, wenn der Host www.nette.org ist:

resolve (string $reference): UrlImmutable

Löst eine absolute URL auf dieselbe Weise auf, wie ein Browser Links auf einer HTML-Seite verarbeitet:

• ist der Link eine absolute URL (enthält ein Schema), wird er unverändert verwendet
• beginnt der Link mit //, wird nur das Schema der aktuellen URL übernommen
• beginnt der Link mit /, entsteht ein absoluter Pfad vom Wurzelverzeichnis der Domain
• in den übrigen Fällen wird die URL relativ zum aktuellen Pfad zusammengesetzt

$url = new UrlImmutable('https://example.com/path/page');
echo $url->resolve('../foo');           // 'https://example.com/foo'
echo $url->resolve('/bar');             // 'https://example.com/bar'
echo $url->resolve('sub/page.html');    // 'https://example.com/path/sub/page.html'

isEqual (string|Url $url): bool

Prüft, ob zwei URLs identisch sind.

$url->isEqual('https://nette.org');

UrlScript

Die Klasse Nette\Http\UrlScript ist ein Nachkomme von UrlImmutable und erweitert sie um weitere virtuelle URL-Komponenten, etwa das Wurzelverzeichnis des Projekts usw. Wie ihre Elternklasse ist sie ein unveränderliches Objekt.

Das folgende Diagramm zeigt die Komponenten, die UrlScript kennt:

     baseUrl    basePath  relativePath  relativeUrl
        |          |        |               |
/---------------/-----\/--------\---------------------------\
http://nette.org/admin/script.php/pathinfo/?name=param#footer
                \_______________/\________/
                       |              |
                  scriptPath       pathInfo

• baseUrl ist die Basis-URL der Anwendung, einschließlich Domain und Pfadteil zum Wurzelverzeichnis der Anwendung
• basePath ist der Pfadteil zum Wurzelverzeichnis der Anwendung
• scriptPath ist der Pfad zum aktuellen Skript
• relativePath ist der Name des Skripts (und eventuell weitere Pfadsegmente) relativ zu basePath
• relativeUrl ist der gesamte Teil der URL nach baseUrl, einschließlich Query-String und Fragment
• pathInfo ist ein heute selten genutzter Teil der URL nach dem Namen des Skripts

Zum Auslesen dieser Teile der URL stehen folgende Methoden zur Verfügung:

Objekte vom Typ UrlScript erzeugen wir normalerweise nicht direkt; stattdessen gibt die Methode Nette\Http\Request::getUrl() eines zurück, dessen Komponenten für den aktuellen HTTP-Request bereits korrekt gesetzt sind.