Praca z adresami URL
Klasy Url, UrlImmutable i UrlScript umożliwiają łatwe generowanie, parsowanie i manipulowanie adresami URL.
Url
Klasa Nette\Http\Url umożliwia łatwą pracę z adresami URL i ich poszczególnymi komponentami, które przedstawia ten schemat:
scheme user password host port path query fragment | | | | | | | | /--\ /--\ /------\ /-------\ /--\/----------\ /--------\ /----\ http://john:xyz%2A12@nette.org:8080/en/download?name=param#footer \______\__________________________/ | | hostUrl authority
Generowanie URL jest intuicyjne:
use Nette\Http\Url;
$url = new Url;
$url->setScheme('https')
->setHost('localhost')
->setPath('/edit')
->setQueryParameter('foo', 'bar');
echo $url; // 'https://localhost/edit?foo=bar'
Można również sparsować URL i dalej nim manipulować:
$url = new Url(
'http://john:xyz%2A12@nette.org:8080/en/download?name=param#footer',
);
Klasa Url
implementuje interfejs JsonSerializable
i ma metodę __toString()
, więc
obiekt można wypisać lub użyć w danych przekazywanych do json_encode()
.
echo $url;
echo json_encode([$url]);
Komponenty URL
Do zwracania lub zmiany poszczególnych komponentów URL dostępne są następujące metody:
Setter | Getter | Zwracana wartość |
---|---|---|
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 |
cały URL |
Uwaga: Pracując z adresem URL uzyskanym z żądania HTTP, pamiętaj, że nie będzie on zawierał fragmentu, ponieważ przeglądarka go nie wysyła na serwer.
Możemy również pracować z poszczególnymi parametrami zapytania za pomocą:
Setter | Getter |
---|---|
setQuery(string|array $query) |
getQueryParameters(): array |
setQueryParameter(string $name, $val) |
getQueryParameter(string $name) |
getDomain (int $level = 2): string
Zwraca prawą lub lewą część hosta. Działa w ten sposób, jeśli host to www.nette.org
:
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
Sprawdza, czy dwa adresy URL są identyczne.
$url->isEqual('https://nette.org');
Url::isAbsolute (string $url): bool
Sprawdza, czy adres URL jest absolutny. Adres URL jest uważany za absolutny, jeśli zaczyna się od schematu (np. http, https, ftp) poprzedzonego dwukropkiem.
Url::isAbsolute('https://nette.org'); // true
Url::isAbsolute('//nette.org'); // false
Url::removeDotSegments (string $path): string
Normalizuje ścieżkę w adresie URL, usuwając specjalne segmenty .
i ..
. Metoda usuwa zbędne
elementy ścieżki w taki sam sposób, jak robią to przeglądarki internetowe.
Url::removeDotSegments('/path/../subtree/./file.txt'); // '/subtree/file.txt'
Url::removeDotSegments('/../foo/./bar'); // '/foo/bar'
Url::removeDotSegments('./today/../file.txt'); // 'file.txt'
UrlImmutable
Klasa Nette\Http\UrlImmutable jest immutable
(niezmienną) alternatywą klasy Url (podobnie jak w PHP DateTimeImmutable
jest niezmienną
alternatywą DateTime
). Zamiast setterów ma tzw. withery, które nie zmieniają obiektu, ale zwracają nowe
instancje ze zmodyfikowaną wartością:
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'
Klasa UrlImmutable
implementuje interfejs JsonSerializable
i ma metodę __toString()
,
więc obiekt można wypisać lub użyć w danych przekazywanych do json_encode()
.
echo $url;
echo json_encode([$url]);
Komponenty URL
Do zwracania lub zmiany poszczególnych komponentów URL służą metody:
Wither | Getter | Zwracana wartość |
---|---|---|
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 |
cały URL |
Metoda withoutUserInfo()
usuwa user
i password
.
Możemy również pracować z poszczególnymi parametrami zapytania za pomocą:
Wither | Getter |
---|---|
withQuery(string|array $query) |
getQueryParameters(): array |
withQueryParameter(string $name, $val) |
getQueryParameter(string $name) |
getDomain (int $level = 2): string
Zwraca prawą lub lewą część hosta. Działa w ten sposób, jeśli host to www.nette.org
:
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
Wyprowadza absolutny adres URL w taki sam sposób, w jaki przeglądarka przetwarza linki na stronie HTML:
- jeśli link jest absolutnym adresem URL (zawiera schemat), jest używany bez zmian
- jeśli link zaczyna się od
//
, pobierany jest tylko schemat z bieżącego adresu URL - jeśli link zaczyna się od
/
, tworzona jest ścieżka absolutna od korzenia domeny - w pozostałych przypadkach adres URL jest budowany względnie do bieżącej ścieżki
$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
Sprawdza, czy dwa adresy URL są identyczne.
$url->isEqual('https://nette.org');
UrlScript
Klasa Nette\Http\UrlScript jest potomkiem UrlImmutable i rozszerza go o dodatkowe wirtualne komponenty URL, takie jak katalog główny projektu itp. Podobnie jak klasa macierzysta, jest obiektem immutable (niezmiennym).
Poniższy diagram przedstawia komponenty, które UrlScript rozpoznaje:
baseUrl basePath relativePath relativeUrl | | | | /---------------/-----\/--------\---------------------------\ http://nette.org/admin/script.php/pathinfo/?name=param#footer \_______________/\________/ | | scriptPath pathInfo
baseUrl
to podstawowy adres URL aplikacji, w tym domena i część ścieżki do katalogu głównego aplikacjibasePath
to część ścieżki do katalogu głównego aplikacjiscriptPath
to ścieżka do bieżącego skrypturelativePath
to nazwa skryptu (ewentualnie dodatkowe segmenty ścieżki) względna dobasePath
relativeUrl
to cała część adresu URL zabaseUrl
, w tym query string i fragment.pathInfo
to dziś rzadko używana część adresu URL za nazwą skryptu
Do zwracania części URL dostępne są metody:
Getter | Zwracana wartość |
---|---|
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/' |
Obiekty UrlScript
zwykle nie tworzymy bezpośrednio, ale zwraca je metoda Nette\Http\Request::getUrl() z już poprawnie ustawionymi komponentami dla
bieżącego żądania HTTP.