URL Parser and Builder
The Url, UrlImmutable, and UrlScript classes make it easy to manage, parse, and manipulate URLs.
→ Installation and requirements
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 Url
class implements the JsonSerializable
interface and provides the __toString()
method, making it possible to print the object or use it with json_encode()
.
echo $url;
echo json_encode([$url]);
URL Components
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 |
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 |
full URL |
Warning: When working with a URL obtained from an HTTP request, keep in mind that it will not contain the fragment, as the browser does not send it to the server.
We can also operate with individual query parameters using:
Setter | Getter |
---|---|
setQuery(string|array $query) |
getQueryParameters(): array |
setQueryParameter(string $name, $val) |
getQueryParameter(string $name) |
getDomain (int $level = 2): string
Returns the right or left part of the host. Here's 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) |
'' |
isEqual (string|Url $anotherUrl): bool
Checks if two URLs are identical.
$url->isEqual('https://nette.org');
Url::isAbsolute (string $url): bool
Checks if a URL is absolute. A URL is considered absolute if it begins with a scheme (e.g., http, https, ftp) followed by a colon.
Url::isAbsolute('https://nette.org'); // true
Url::isAbsolute('//nette.org'); // false
Url::removeDotSegments (string $path): string
Normalizes a URL path by removing special segments .
and ..
. This method removes redundant path
elements the same way browsers do.
Url::removeDotSegments('/path/../subtree/./file.txt'); // '/subtree/file.txt'
Url::removeDotSegments('/../foo/./bar'); // '/foo/bar'
Url::removeDotSegments('./today/../file.txt'); // 'file.txt'
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 UrlImmutable
class implements the JsonSerializable
interface and provides the
__toString()
method, allowing you to print the object or use it with json_encode()
.
echo $url;
echo json_encode([$url]);
URL Components
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 |
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 |
full URL |
The withoutUserInfo()
method removes user
and password
.
We can also operate with individual query parameters using:
Wither | Getter |
---|---|
withQuery(string|array $query) |
getQueryParameters(): array |
withQueryParameter(string $name, $val) |
getQueryParameter(string $name) |
getDomain (int $level = 2): string
Returns the right or left part of the host. Here's 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) |
'' |
resolve (string $reference): UrlImmutable
Resolves an absolute URL in the same way a browser processes links on an HTML page:
- If the link is an absolute URL (contains a scheme), it is used unchanged.
- If the link begins with
//
, only the scheme from the current URL is applied. - If the link begins with
/
, an absolute path from the domain root is created. - In other cases, the URL is constructed relative to the current path.
$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
Checks if two URLs are identical.
$url->isEqual('https://nette.org');
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.