URL Utility
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:
You can also parse the URL and then manipulate it:
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()
.
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 |
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::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::removeDotSegments(string $path): string
Normalizes a URL path by removing special segments .
and ..
. This method removes redundant path
elements the same way browsers do.
UrlImmutable
The Nette\Http\UrlImmutable class is an immutable
alternative to the Url class (similar to how DateTimeImmutable
is an immutable alternative to
DateTime
in PHP). Instead of setters, it has withers, which do not change the object but return new instances with
the modified value:
The UrlImmutable
class implements the JsonSerializable
interface and provides the
__toString()
method, allowing you to print the object or use it with json_encode()
.
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.
isEqual(string|Url $anotherUrl): bool
Checks if two URLs are identical.
UrlScript
The Nette\Http\UrlScript class is a descendant of UrlImmutable and extends it with additional virtual URL components, such as the root directory of the project, etc. Like its parent class, it is an immutable object.
The following diagram shows the components that UrlScript recognizes:
baseUrl basePath relativePath relativeUrl | | | | /---------------/-----\/--------\---------------------------\ http://nette.org/admin/script.php/pathinfo/?name=param#footer \_______________/\________/ | | scriptPath pathInfo
baseUrl
is the base URL of the application including domain and part of the path to the root directory of the applicationbasePath
is part of the path to the root directory of the applicationscriptPath
is the path to the current scriptrelativePath
is the script name (and possibly additional path segments) relative to basePathrelativeUrl
is the entire part of the URL after baseUrl, including query string and fragment.pathInfo
is a now rarely used part of the URL after the script name
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.