Nette Documentation Preview

syntax 
Arbeiten mit URLs
*****************

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

→ [Installation und Anforderungen |@home#Installation]


Url
===

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

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

Das Generieren von URLs ist intuitiv:

```php
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:

```php
$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.

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


URL-Komponenten .[method]
-------------------------

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

.[language-php]
| Setter									| Getter						| Zurückgegebener Wert
|--------------------------------------------------------------------------------------------
| `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`		| `'john:xyz%2A12@nette.org:8080'`
| 											| `getHostUrl(): string`		| `'http://john:xyz%2A12@nette.org:8080'`
| 											| `getAbsoluteUrl(): string` 	| ganze URL

Warnung: Wenn Sie mit einer URL arbeiten, die aus einer [HTTP-Anfrage |request] 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:

.[language-php]
| Setter									| Getter
|---------------------------------------------------
| `setQuery(string\|array $query)`  		| `getQueryParameters(): array`
| `setQueryParameter(string $name, $val)`	| `getQueryParameter(string $name)`


getDomain(int $level = 2): string .[method]
-------------------------------------------
Gibt den rechten oder linken Teil des Hosts zurück. So funktioniert es, wenn der Host `www.nette.org` ist:

.[language-php]
| `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)` |  `''`


isEqual(string|Url $anotherUrl): bool .[method]
-----------------------------------------------
Überprüft, ob zwei URLs identisch sind.

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


Url::isAbsolute(string $url): bool .[method]{data-version:3.3.2}
----------------------------------------------------------------
Ü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.

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


Url::removeDotSegments(string $path): string .[method]{data-version:3.3.2}
--------------------------------------------------------------------------
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.

```php
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 [api: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:

```php
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.

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


URL-Komponenten .[method]
-------------------------

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

.[language-php]
| Wither									| Getter						| Zurückgegebener Wert
|--------------------------------------------------------------------------------------------
| `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`		| `'john:xyz%2A12@nette.org:8080'`
| 											| `getHostUrl(): string`		| `'http://john:xyz%2A12@nette.org:8080'`
| 											| `getAbsoluteUrl(): string` 	| ganze URL

Die Methode `withoutUserInfo()` entfernt `user` und `password`.

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

.[language-php]
| Wither								| Getter
|-----------------------------------------------
| `withQuery(string\|array $query)` 	    | `getQueryParameters(): array`
| `withQueryParameter(string $name, $val)`  | `getQueryParameter(string $name)`


getDomain(int $level = 2): string .[method]
-------------------------------------------
Gibt den rechten oder linken Teil des Hosts zurück. So funktioniert es, wenn der Host `www.nette.org` ist:

.[language-php]
| `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)` |  `''`


resolve(string $reference): UrlImmutable .[method]{data-version:3.3.2}
----------------------------------------------------------------------
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

```php
$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 .[method]
-----------------------------------------------
Überprüft, ob zwei URLs identisch sind.

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


UrlScript
=========

Die Klasse [api: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:

/--pre
      baseUrl    basePath  relativePath  relativeUrl
         |          |        |               |
 /---------------/-----\/--------\---------------------------\
 <b>http://nette.org/admin/script.php/pathinfo/?name=param#footer</b>
                 \_______________/\________/
                        |              |
                   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:

.[language-php]
| Getter						| Zurückgegebener Wert
|------------------------------------------------
| `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/'`

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

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:

Setter Getter Zurückgegebener Wert
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 'john:xyz%2A12@nette.org:8080'
  getHostUrl(): string 'http://john:xyz%2A12@nette.org:8080'
  getAbsoluteUrl(): string ganze URL

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:

Setter Getter
setQuery(string|array $query) getQueryParameters(): array
setQueryParameter(string $name, $val) getQueryParameter(string $name)

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:

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) ''

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:

Wither Getter Zurückgegebener Wert
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 'john:xyz%2A12@nette.org:8080'
  getHostUrl(): string 'http://john:xyz%2A12@nette.org:8080'
  getAbsoluteUrl(): string ganze URL

Die Methode withoutUserInfo() entfernt user und password.

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

Wither Getter
withQuery(string|array $query) getQueryParameters(): array
withQueryParameter(string $name, $val) getQueryParameter(string $name)

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:

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) ''

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:

Getter Zurückgegebener Wert
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/'

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.