Parser e costruttore di URL

Le classi Url, UrlImmutable e UrlScript semplificano la gestione, l'analisi e la manipolazione degli URL.

Url

La classe Nette\Http\Url semplifica il lavoro con l'URL e i suoi singoli componenti, che sono illustrati in questo diagramma:

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

La generazione di URL è intuitiva:

use Nette\Http\Url;

$url = new Url;
$url->setScheme('https')
	->setHost('localhost')
	->setPath('/edit')
	->setQueryParameter('foo', 'bar');

echo $url; // 'https://localhost/edit?foo=bar'

È anche possibile analizzare l'URL e poi manipolarlo:

$url = new Url(
	'http://john:xyz%2A12@nette.org:8080/en/download?name=param#footer',
);

Per ottenere o modificare singoli componenti dell'URL sono disponibili i seguenti metodi:

Setter	Getter	Valore restituito
`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`	URL completo

Attenzione: Quando si lavora con un URL ottenuto da una richiesta HTTP, tenere presente che non conterrà il frammento, poiché il browser non lo invia al server.

Possiamo anche operare con singoli parametri di query utilizzando:

Setter	Getter
`setQuery(string\|array $query)`	`getQueryParameters(): array`
`setQueryParameter(string $name, $val)`	`getQueryParameter(string $name)`

Il metodo getDomain(int $level = 2) restituisce la parte destra o sinistra dell'host. Funziona così se l'host è 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)`	`''`

La classe Url implementa l'interfaccia JsonSerializable e ha un metodo __toString() che consente di stampare l'oggetto o di utilizzarlo nei dati passati a json_encode().

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

Il metodo isEqual(string|Url $anotherUrl): bool verifica se i due URL sono identici.

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

UrlImmutabile

La classe Nette\Http\UrlImmutable è un'alternativa immutabile alla classe Url (così come in PHP DateTimeImmutable è un'alternativa immutabile a DateTime). Al posto dei setter, ha i cosiddetti wither, che non modificano l'oggetto, ma restituiscono nuove istanze con un valore modificato:

use Nette\Http\UrlImmutable;

$url = new UrlImmutable(
	'http://john:xyz%2A12@nette.org:8080/en/download?name=param#footer',
);

$newUrl = $url
	->withUser('')
	->withPassword('')
	->withPath('/en/');

echo $newUrl; // 'http://nette.org:8080/en/?name=param#footer'

I seguenti metodi sono disponibili per ottenere o modificare singoli componenti dell'URL:

Contiene	Getter	Valore restituito
`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`	URL completo

Possiamo anche operare con singoli parametri di query utilizzando:

Wither	Getter
`withQuery(string\|array $query)`	`getQueryParameters(): array`
`withQueryParameter(string $name, $val)`	`getQueryParameter(string $name)`

Il metodo getDomain(int $level = 2) funziona come il metodo in Url. Il metodo withoutUserInfo() rimuove user e password.

La classe UrlImmutable implementa l'interfaccia JsonSerializable e ha un metodo __toString() che consente di stampare l'oggetto o di utilizzarlo nei dati passati a json_encode().

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

Il metodo isEqual(string|Url $anotherUrl): bool verifica se i due URL sono identici.

UrlScript

La classe Nette\Http\UrlScript è un discendente di UrlImmutable e distingue inoltre queste parti logiche dell'URL:

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

Per ottenere queste parti sono disponibili i seguenti metodi:

Getter	Valore restituito
`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/'`

Non creiamo direttamente l'oggetto UrlScript, ma il metodo Nette\Http\Request::getUrl() lo restituisce.