URL-Parser und -Ersteller
Die Klassen Url, UrlImmutable und UrlScript erleichtern das Verwalten, Parsen und Manipulieren von URLs.
→ Installation und Anforderungen
Url
Die Klasse Nette\Http\Url erleichtert die Arbeit mit der URL und ihren einzelnen Komponenten, die in diesem Diagramm skizziert werden:
scheme user password host port path query fragment
| | | | | | | |
/--\ /--\ /------\ /-------\ /--\/----------\ /--------\ /----\
http://john:xyz%2A12@nette.org:8080/en/download?name=param#footer
\______\__________________________/
| |
hostUrl authority
Die URL-Generierung 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 die URL auch parsen und dann manipulieren:
$url = new Url(
'http://john:xyz%2A12@nette.org:8080/en/download?name=param#footer',
);
Die folgenden Methoden stehen zur Verfügung, um einzelne URL-Komponenten zu erhalten oder zu ändern:
| Setter | Getter | Rückgabewert |
|---|---|---|
setScheme(string $scheme) |
getScheme(): string |
'http' |
setUser(string $user) |
getUser(): string |
'john' |
setPassword(string $password) |
getPassword(): string |
'xyz*12' |
setHost(string $host) |
getHost(): string |
'nette.org' |
setPort(int $port) |
getPort(): ?int |
8080 |
getDefaultPort(): ?int |
80 |
|
setPath(string $path) |
getPath(): string |
'/en/download' |
setQuery(string|array $query) |
getQuery(): string |
'name=param' |
setFragment(string $fragment) |
getFragment(): string |
'footer' |
getAuthority(): string |
'nette.org:8080' |
|
getHostUrl(): string |
'http://nette.org:8080' |
|
getAbsoluteUrl(): string |
vollständige URL |
Warnung: Bei der Arbeit mit einer URL, die aus einer HTTP-Anfrage stammt, ist zu beachten, dass sie das Fragment nicht enthält, da der Browser es nicht an den Server sendet.
Wir können auch mit einzelnen Abfrageparametern arbeiten:
| Setter | Getter |
|---|---|
setQuery(string|array $query) |
getQueryParameters(): array |
setQueryParameter(string $name, $val) |
getQueryParameter(string $name) |
Die Methode getDomain(int $level = 2) gibt den rechten oder linken Teil des Hosts zurück. So funktioniert es,
wenn der Host www.nette.org ist:
getDomain(1) |
'org' |
getDomain(2) |
'nette.org' |
getDomain(3) |
'www.nette.org' |
getDomain(0) |
'www.nette.org' |
getDomain(-1) |
'www.nette' |
getDomain(-2) |
'www' |
getDomain(-3) |
'' |
Die Klasse Url implementiert die Schnittstelle JsonSerializable und verfügt über eine Methode
__toString(), damit das Objekt gedruckt oder in Daten verwendet werden kann, die an json_encode()
übergeben werden.
echo $url;
echo json_encode([$url]);
Die Methode isEqual(string|Url $anotherUrl): bool prüft, ob die beiden URLs identisch sind.
$url->isEqual('https://nette.org');
UrlImmutable
Die Klasse Nette\Http\UrlImmutable ist eine
unveränderbare Alternative zur Klasse Url (so wie in PHP DateTimeImmutable eine unveränderbare
Alternative zu DateTime ist). Anstelle von Settern hat sie sogenannte Wither, die das Objekt nicht verändern,
sondern neue Instanzen mit einem 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('/en/');
echo $newUrl; // 'http://nette.org:8080/en/?name=param#footer'
Die folgenden Methoden stehen zur Verfügung, um einzelne URL-Komponenten zu erhalten oder zu ändern:
| Wither | Getter | Rückgabewert |
|---|---|---|
withScheme(string $scheme) |
getScheme(): string |
'http' |
withUser(string $user) |
getUser(): string |
'john' |
withPassword(string $password) |
getPassword(): string |
'xyz*12' |
withHost(string $host) |
getHost(): string |
'nette.org' |
withPort(int $port) |
getPort(): ?int |
8080 |
getDefaultPort(): ?int |
80 |
|
withPath(string $path) |
getPath(): string |
'/en/download' |
withQuery(string|array $query) |
getQuery(): string |
'name=param' |
withFragment(string $fragment) |
getFragment(): string |
'footer' |
getAuthority(): string |
'nette.org:8080' |
|
getHostUrl(): string |
'http://nette.org:8080' |
|
getAbsoluteUrl(): string |
vollständige URL |
Wir können auch mit einzelnen Abfrageparametern arbeiten:
| Wither | Getter |
|---|---|
withQuery(string|array $query) |
getQueryParameters(): array |
withQueryParameter(string $name, $val) |
getQueryParameter(string $name) |
Die Methode getDomain(int $level = 2) funktioniert genauso wie die Methode in Url. Mit der Methode
withoutUserInfo() werden user und password entfernt.
Die Klasse UrlImmutable implementiert die Schnittstelle JsonSerializable und verfügt über eine
Methode __toString(), damit das Objekt gedruckt oder in Daten verwendet werden kann, die an
json_encode() übergeben werden.
echo $url;
echo json_encode([$url]);
Die Methode isEqual(string|Url $anotherUrl): bool prüft, ob die beiden URLs identisch sind.
UrlScript
Die Klasse Nette\Http\UrlScript ist ein Abkömmling von
UrlImmutable und unterscheidet zusätzlich diese logischen Teile der URL:
baseUrl basePath relativePath relativeUrl
| | | |
/---------------/-----\/--------\---------------------------\
http://nette.org/admin/script.php/pathinfo/?name=param#footer
\_______________/\________/
| |
scriptPath pathInfo
Die folgenden Methoden sind verfügbar, um diese Teile zu erhalten:
| Getter | Rückgabewert |
|---|---|
getScriptPath(): string |
'/admin/script.php' |
getBasePath(): string |
'/admin/' |
getBaseUrl(): string |
'http://nette.org/admin/' |
getRelativePath(): string |
'script.php' |
getRelativeUrl(): string |
'script.php/pathinfo/?name=param#footer' |
getPathInfo(): string |
'/pathinfo/' |
Wir erstellen die Objekte UrlScript nicht direkt, aber die Methode Nette\Http\Request::getUrl() gibt sie zurück.