URL-Parser und -Ersteller

Die Klassen Url, UrlImmutable und UrlScript erleichtern das Verwalten, Parsen und Manipulieren von URLs.

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

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.