Nette Documentation Preview

syntax 
URL Parser and Builder
**********************

.[perex]
The [#Url], [#UrlImmutable], and [#UrlScript] classes make it easy to manage, parse, and manipulate URLs.

→ [Installation and requirements |@home#Installation]


Url
===

The [api:Nette\Http\Url] class makes it easy to work with the URL and its individual components, which are outlined in this diagram:

/--pre
 scheme  user  password  host   port    path        query  fragment
   |      |      |        |      |       |            |       |
 /--\   /--\ /------\ /-------\ /--\/----------\ /--------\ /----\
 <b>http://john:xyz%2A12@nette.org:8080/en/download?name=param#footer</b>
 \______\__________________________/
     |               |
  hostUrl        authority
\--

URL generation is intuitive:

```php
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:

```php
$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:

.[language-php]
| 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|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:

.[language-php]
| 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`:

.[language-php]
| `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()`.

```php
echo $url;
echo json_encode([$url]);
```

Method `isEqual(string|Url $anotherUrl): bool` tests whether the two URLs are identical.

```php
$url->isEqual('https://nette.org');
```


UrlImmutable
============

The class [api: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:

```php
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:

.[language-php]
| 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

We can also operate with individual query parameters using:

.[language-php]
| Wither								| Getter
|-----------------------------------------------
| `withQuery(string\|array $query)` 	    | `getQueryParameters(): array`
| `withQueryParameter(string $name, $val)`  | `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()`.

```php
echo $url;
echo json_encode([$url]);
```

Method `isEqual(string|Url $anotherUrl): bool` tests whether the two URLs are identical.


UrlScript
=========

The [api:Nette\Http\UrlScript] class is a descendant of `UrlImmutable` and additionally distinguishes these logical parts of the URL:

/--pre
      baseUrl    basePath  relativePath  relativeUrl
         |          |        |               |
 /---------------/-----\/--------\---------------------------\
 <b>http://nette.org/admin/script.php/pathinfo/?name=param#footer</b>
                 \_______________/\________/
                        |              |
                   scriptPath       pathInfo
\--

The following methods are available to get these parts:

.[language-php]
| 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() |request] returns it.

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 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)

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
  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

We can also operate with individual query parameters using:

Wither Getter
withQuery(string|array $query) getQueryParameters(): array
withQueryParameter(string $name, $val) 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.