Arbeiten mit URLs

Die Klassen Url, UrlImmutable und UrlScript ermöglichen das einfache Generieren, Parsen und Manipulieren von URLs.

→ Installation und Anforderungen

Url

Die Klasse Nette\Http\Url ermöglicht das einfache Arbeiten mit URLs und ihren einzelnen Komponenten, die diese Skizze erfasst:

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

Das Generieren 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'

Es ist auch möglich, eine URL zu parsen und weiter zu manipulieren:

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

Die Klasse Url implementiert die Schnittstelle JsonSerializable und hat die Methode __toString(), sodass das Objekt ausgegeben oder in Daten verwendet werden kann, die an json_encode() übergeben werden.

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

URL-Komponenten

Zum Abrufen oder Ändern einzelner URL-Komponenten stehen Ihnen diese Methoden zur Verfügung:

Warnung: Wenn Sie mit einer URL arbeiten, die aus einer HTTP-Anfrage stammt, beachten Sie, dass sie kein Fragment enthalten wird, da der Browser es nicht an den Server sendet.

Wir können auch mit einzelnen Query-Parametern arbeiten mittels:

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 $anotherUrl): bool

Überprüft, ob zwei URLs identisch sind.

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

Url::isAbsolute (string $url): bool

Überprüft, ob die URL absolut ist. Eine URL wird als absolut betrachtet, 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 den Pfad in einer URL durch Entfernen der speziellen Segmente . und ... Die Methode entfernt überflüssige Pfadelemente auf die gleiche Weise, wie es Webbrowser tun.

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 immutable (unveränderliche) Alternative zur Klasse Url (ähnlich wie in PHP DateTimeImmutable eine unveränderliche Alternative zu DateTime ist). Anstelle von Settern hat sie sogenannte Wither, die das Objekt nicht ändern, sondern neue Instanzen mit dem geänderten Wert zurückgeben:

use Nette\Http\UrlImmutable;

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

$newUrl = $url
	->withUser('')
	->withPassword('')
	->withPath('/cs/');

echo $newUrl; // 'http://john:xyz%2A12@nette.org:8080/cs/?name=param#footer'

Die Klasse UrlImmutable implementiert die Schnittstelle JsonSerializable und hat die Methode __toString(), sodass das Objekt ausgegeben oder in Daten verwendet werden kann, die an json_encode() übergeben werden.

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

URL-Komponenten

Zum Abrufen oder Ändern einzelner URL-Komponenten dienen Methoden:

Die Methode withoutUserInfo() entfernt user und password.

Wir können auch mit einzelnen Query-Parametern arbeiten mittels:

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

Leitet eine absolute URL auf die gleiche Weise ab, wie ein Browser Links auf einer HTML-Seite verarbeitet:

• wenn der Link eine absolute URL ist (Schema enthält), wird er unverändert verwendet
• wenn der Link mit // beginnt, wird nur das Schema aus der aktuellen URL übernommen
• wenn der Link mit / beginnt, wird ein absoluter Pfad vom Domain-Stamm erstellt
• in anderen Fällen wird die URL relativ zum aktuellen Pfad zusammengestellt

$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 $anotherUrl): bool

Überprüft, ob zwei URLs identisch sind.

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

UrlScript

Die Klasse Nette\Http\UrlScript ist ein Nachkomme von UrlImmutable und erweitert diese um weitere virtuelle URL-Komponenten, wie das Stammverzeichnis des Projekts usw. Wie die übergeordnete Klasse ist sie ein immutables (unveränderliches) Objekt.

Das folgende Diagramm zeigt die Komponenten, die UrlScript erkennt:

     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 Stammverzeichnis der Anwendung
• basePath ist der Pfadteil zum Stammverzeichnis der Anwendung
• scriptPath ist der Pfad zum aktuellen Skript
• relativePath ist der Name des Skripts (ggf. weitere Pfadsegmente) relativ zum 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 Skriptnamen

Zum Abrufen von URL-Teilen stehen Methoden zur Verfügung:

Objekte UrlScript erstellen wir normalerweise nicht direkt, sondern sie werden von der Methode Nette\Http\Request::getUrl() mit bereits korrekt eingestellten Komponenten für die aktuelle HTTP-Anfrage zurückgegeben.