URL Parser and Builder
The Url, UrlImmutable, and UrlScript classes make it easy to manage, parse, and manipulate URLs.
Installation:
composer require nette/http
Url
The Nette\Http\Url class makes it easy to work with the URL and its individual components, which are outlined in this diagram:
scheme user password host port path query fragment | | | | | | | | /--\ /--\ /------\ /-------\ /--\/----------\ /--------\ /----\ http://john:xyz%2A12@nette.org:8080/en/download?name=param#footer \______\__________________________/ | | hostUrl authority
URL generation is intuitive:
use Nette\Http\Url;
$url = new Url;
$url->setScheme('https')
->setHost('localhost')
->setPath('/edit')
->setQueryParameter('foo', 'bar');
echo $url; // 'https://localhost/edit?foo=bar'
You can also parse the URL and then manipulate it:
$url = new Url(
'http://john:xyz%2A12@nette.org:8080/en/download?name=param#footer'
);
The following methods are available to get or change individual URL components:
Setter | Getter | Returned value |
---|---|---|
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 |
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 |
full URL |
We can also operate with individual query parameters using:
Setter | Getter |
---|---|
setQuery(string|array $query) |
getQueryParameters(): array |
setQueryParameter(string $name, $val) |
getQueryParameter(string $name) |
Method getDomain(int $level = 2)
returns the right or left part of the host. This is how it works if the host is
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) |
'' |
The Url
class implements the JsonSerializable
interface and has a __toString()
method so
that the object can be printed or used in data passed to json_encode()
.
echo $url;
echo json_encode([$url]);
Method isEqual(string|Url $anotherUrl): bool
tests whether the two URLs are identical.
$url->isEqual('https://nette.org');
UrlImmutable
The class Nette\Http\UrlImmutable is an immutable
alternative to class Url
(just as in PHP DateTimeImmutable
is immutable alternative to
DateTime
). Instead of setters, it has so-called withers, which do not change the object, but return new instances
with a modified value:
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://nette.org:8080/cs/?name=param#footer'
The following methods are available to get or change individual URL components:
Wither | Getter | Returned value |
---|---|---|
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 |
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 |
full URL |
We can also operate with individual query parameters using:
Wither | Getter |
---|---|
withQuery(string|array $query) |
getQueryParameters(): array |
getQueryParameter(string $name) |
The getDomain(int $level = 2)
method works the same as the method in Url
. Method
withoutUserInfo()
removes user
and password
.
The UrlImmutable
class implements the JsonSerializable
interface and has a __toString()
method so that the object can be printed or used in data passed to json_encode()
.
echo $url;
echo json_encode([$url]);
Method isEqual(string|Url $anotherUrl): bool
tests whether the two URLs are identical.
UrlScript
The Nette\Http\UrlScript class is a descendant of
UrlImmutable
and additionally distinguishes these logical parts of the URL:
baseUrl basePath relativePath relativeUrl | | | | /---------------/-----\/--------\---------------------------\ http://nette.org/admin/script.php/pathinfo/?name=param#footer \_______________/\________/ | | scriptPath pathInfo
The following methods are available to get these parts:
Getter | Returned value |
---|---|
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/' |
We do not create objects UrlScript
directly, but the method Nette\Http\Request::getUrl() returns it.
Related blog posts
News in Nette Http 3.1
News in Nette Http version 3.1 mainly concerns the current development of browsers in relation to cookies. Current browsers finally work without bugs…
HTTP requests and responses – Part 3
In the first and second sections of this mini-series I describe the possibilities of controlling HTTP protocol from the presenter in Nette…
HTTP requests and responses – Part 2
In the first part I describe presenter methods, by which we can control HTTP responses of the application. In this section, I will address the…
HTTP requests and responses – Part 1
Nette offers two layers of abstraction to work with HTTP. The first, low-level, is provided by namespace classes Nette\Http. They offer a nice API…