Analyseur et constructeur d'URL

Les classes Url, UrlImmutable et UrlScript permettent de gérer, d'analyser et de manipuler facilement les URL.

Url

La classe Nette\Http\Url permet de travailler facilement avec l'URL et ses composants individuels, qui sont décrits dans ce diagramme :

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

La génération d'URL est 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'

Vous pouvez également analyser l'URL, puis la manipuler :

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

Les méthodes suivantes sont disponibles pour obtenir ou modifier des composants individuels de l'URL :

Setter	Getter	Valeur retournée
`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 complète

Attention : Lorsque vous travaillez avec une URL obtenue à partir d'une requête HTTP, gardez à l'esprit qu'elle ne contiendra pas le fragment, car le navigateur ne l'envoie pas au serveur.

Nous pouvons également opérer avec des paramètres de requête individuels en utilisant :

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

La méthode getDomain(int $level = 2) renvoie la partie droite ou gauche de l'hôte. Voici comment cela fonctionne si l'hôte est 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 implémente l'interface JsonSerializable et possède une méthode __toString() afin que l'objet puisse être imprimé ou utilisé dans les données transmises à json_encode().

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

La méthode isEqual(string|Url $anotherUrl): bool teste si les deux URL sont identiques.

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

UrlImmutable

La classe Nette\Http\UrlImmutable est une alternative immuable à la classe Url (tout comme en PHP DateTimeImmutable est une alternative immuable à DateTime). Au lieu de setters, elle a ce qu'on appelle des garrots, qui ne changent pas l'objet, mais retournent de nouvelles instances avec une valeur modifiée :

use Nette\Http\UrlImmutable;

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

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

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

Les méthodes suivantes sont disponibles pour obtenir ou modifier des composants individuels d'URL :

Wither	Getter	Valeur retournée
`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 complète

Nous pouvons également opérer avec des paramètres de requête individuels en utilisant :

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

La méthode getDomain(int $level = 2) fonctionne de la même manière que la méthode Url. La méthode withoutUserInfo() supprime user et password.

La classe UrlImmutable implémente l'interface JsonSerializable et possède une méthode __toString() afin que l'objet puisse être imprimé ou utilisé dans les données transmises à json_encode().

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

La méthode isEqual(string|Url $anotherUrl): bool teste si les deux URL sont identiques.

UrlScript

La classe Nette\Http\UrlScript est un descendant de UrlImmutable et distingue en plus ces parties logiques de l'URL :

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

Les méthodes suivantes sont disponibles pour obtenir ces parties :

Getter	Valeur retournée
`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/'`

Nous ne créons pas directement l'objet UrlScript, mais la méthode Nette\Http\Request::getUrl() le renvoie.