Travailler avec les URL
***********************
.[perex]
Les classes [#Url], [#UrlImmutable] et [#UrlScript] facilitent la génération, l'analyse et la manipulation des URL.
→ [Installation et prérequis |@home#Installation]
Url
===
La classe [api:Nette\Http\Url] permet de manipuler facilement les URL et leurs différents composants, comme le montre ce schéma :
/--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
\--
Générer des URL est intuitif :
```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'
```
Vous pouvez aussi analyser une URL puis la manipuler :
```php
$url = new Url(
'http://john:xyz%2A12@nette.org:8080/en/download?name=param#footer',
);
```
La classe `Url` implémente l'interface `JsonSerializable` et possède une méthode `__toString()`, l'objet peut donc être affiché ou utilisé dans les données passées à `json_encode()`.
```php
echo $url;
echo json_encode([$url]);
```
Composants de l'URL
-------------------
Les méthodes suivantes permettent d'obtenir ou de modifier les différents composants de l'URL :
.[language-php]
| Setter | Getter | Valeur renvoyé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` | `'john:xyz%2A12@nette.org:8080'`
| | `getHostUrl(): string` | `'http://john:xyz%2A12@nette.org:8080'`
| | `getAbsoluteUrl(): string` | l'URL entière
Les méthodes `getUser()`, `getPassword()`, `setUser()` et `setPassword()` sont obsolètes, car intégrer des identifiants directement dans une URL est déconseillé.
Attention : lorsque vous travaillez avec une URL obtenue depuis une [requête HTTP |request], gardez à l'esprit qu'elle ne contiendra pas le fragment, car le navigateur ne l'envoie pas au serveur.
Nous pouvons aussi travailler sur les différents paramètres de la query string à l'aide de :
.[language-php]
| Setter | Getter
|---------------------------------------------------
| `setQuery(string\|array $query)` | `getQueryParameters(): array`
| `setQueryParameter(string $name, $val)` | `getQueryParameter(string $name)`
| `appendQuery(string\|array $query)` |
getDomain(int $level = 2): string .[method]
-------------------------------------------
Renvoie la partie droite ou gauche de l'hôte. Voici comment cela fonctionne si l'hôte est `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)` | `''`
isEqual(string|Url $url): bool .[method]
----------------------------------------
Vérifie si deux URL sont identiques.
```php
$url->isEqual('https://nette.org');
```
canonicalize() .[method]
------------------------
Convertit l'URL en forme canonique. Cela met le nom d'hôte en minuscules et normalise le chemin (encodage pour cent et suppression des caractères superflus). La query string reste inchangée.
Url::isAbsolute(string $url): bool .[method]{data-version:3.3.2}
----------------------------------------------------------------
Vérifie si une URL est absolue. Une URL est considérée comme absolue si elle commence par un schéma (par exemple http, https, ftp) suivi de deux-points.
```php
Url::isAbsolute('https://nette.org'); // true
Url::isAbsolute('//nette.org'); // false
```
Url::removeDotSegments(string $path): string .[method]{data-version:3.3.2}
--------------------------------------------------------------------------
Normalise le chemin d'une URL en supprimant les segments spéciaux `.` et `..`. Cette méthode supprime les éléments de chemin superflus de la même façon que les navigateurs web.
```php
Url::removeDotSegments('/path/../subtree/./file.txt'); // '/subtree/file.txt'
Url::removeDotSegments('/../foo/./bar'); // '/foo/bar'
Url::removeDotSegments('./today/../file.txt'); // 'file.txt'
```
UrlImmutable
============
La classe [api:Nette\Http\UrlImmutable] est une alternative immuable à la classe [#Url] (de la même façon que `DateTimeImmutable` est l'alternative immuable de `DateTime` en PHP). Au lieu de setters, elle possède des "withers", qui ne modifient pas l'objet mais renvoient de nouvelles instances portant la valeur modifiée :
```php
use Nette\Http\UrlImmutable;
$url = new UrlImmutable(
'https://nette.org:8080/en/download?name=param#footer',
);
$newUrl = $url
->withHost('example.com')
->withPath('/en/')
->withQueryParameter('name', 'value');
echo $newUrl; // 'https://example.com:8080/en/?name=value#footer'
```
La classe `UrlImmutable` implémente l'interface `JsonSerializable` et possède une méthode `__toString()`, l'objet peut donc être affiché ou utilisé dans les données passées à `json_encode()`.
```php
echo $url;
echo json_encode([$url]);
```
Composants de l'URL
-------------------
Les méthodes suivantes permettent d'obtenir ou de changer les différents composants de l'URL :
.[language-php]
| Wither | Getter | Valeur renvoyé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` | `'john:xyz%2A12@nette.org:8080'`
| | `getHostUrl(): string` | `'http://john:xyz%2A12@nette.org:8080'`
| | `getAbsoluteUrl(): string` | l'URL entière
Les méthodes `getUser()`, `getPassword()`, `withUser()`, `withPassword()` et `withoutUserInfo()` sont obsolètes, car intégrer des identifiants directement dans une URL est déconseillé.
Nous pouvons aussi travailler sur les différents paramètres de la query string à l'aide de :
.[language-php]
| Wither | Getter
|-----------------------------------------------
| `withQuery(string\|array $query)` | `getQueryParameters(): array`
| `withQueryParameter(string $name, $val)` | `getQueryParameter(string $name)`
getDomain(int $level = 2): string .[method]
-------------------------------------------
Renvoie la partie droite ou gauche de l'hôte. Voici comment cela fonctionne si l'hôte est `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)` | `''`
resolve(string $reference): UrlImmutable .[method]{data-version:3.3.2}
----------------------------------------------------------------------
Résout une URL absolue de la même façon qu'un navigateur traite les liens d'une page HTML :
- si le lien est une URL absolue (contient un schéma), il est utilisé tel quel
- si le lien commence par `//`, seul le schéma de l'URL courante est repris
- si le lien commence par `/`, un chemin absolu depuis la racine du domaine est créé
- dans les autres cas, l'URL est construite relativement au chemin courant
```php
$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 $url): bool .[method]
----------------------------------------
Vérifie si deux URL sont identiques.
```php
$url->isEqual('https://nette.org');
```
UrlScript
=========
La classe [api:Nette\Http\UrlScript] est un descendant d'[#UrlImmutable] et l'étend de composants d'URL virtuels supplémentaires, comme le répertoire racine du projet, etc. Comme sa classe parente, c'est un objet immuable.
Le schéma suivant montre les composants que reconnaît UrlScript :
/--pre
baseUrl basePath relativePath relativeUrl
| | | |
/---------------/-----\/--------\---------------------------\
<b>http://nette.org/admin/script.php/pathinfo/?name=param#footer</b>
\_______________/\________/
| |
scriptPath pathInfo
\--
- `baseUrl` est l'URL de base de l'application, domaine compris, jusqu'au répertoire racine de l'application
- `basePath` est la partie chemin menant au répertoire racine de l'application
- `scriptPath` est le chemin du script courant
- `relativePath` est le nom du script (et éventuellement d'autres segments de chemin) relativement à `basePath`
- `relativeUrl` est toute la partie de l'URL située après `baseUrl`, query string et fragment compris
- `pathInfo` est une partie de l'URL, aujourd'hui rarement utilisée, située après le nom du script
Les méthodes suivantes permettent d'obtenir ces parties de l'URL :
.[language-php]
| Getter | Valeur renvoyée
|------------------------------------------------
| `getScriptPath(): string` | `'/admin/script.php'`
| `getBasePath(): string` | `'/admin/'`
| `getBaseUrl(): string` | `'http://nette.org/admin/'`
| `getRelativePath(): string` | `'script.php/pathinfo/'`
| `getRelativeUrl(): string` | `'script.php/pathinfo/?name=param#footer'`
| `getPathInfo(): string` | `'/pathinfo/'`
Nous ne créons généralement pas les objets `UrlScript` directement ; c'est la méthode [Nette\Http\Request::getUrl() |request] qui le renvoie, avec les composants déjà correctement renseignés pour la requête HTTP courante.
Travailler avec les URL
Les classes Url, UrlImmutable et UrlScript facilitent la génération, l'analyse et la manipulation des URL.
→ Installation et prérequis
Url
La classe Nette\Http\Url permet de manipuler facilement les
URL et leurs différents composants, comme le montre ce schéma :
scheme user password host port path query fragment
| | | | | | | |
/--\ /--\ /------\ /-------\ /--\/----------\ /--------\ /----\
http://john:xyz%2A12@nette.org:8080/en/download?name=param#footer
\______\__________________________/
| |
hostUrl authority
Générer des URL est intuitif :
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 aussi analyser une URL puis la manipuler :
$url = new Url(
'http://john:xyz%2A12@nette.org:8080/en/download?name=param#footer',
);
La classe Url implémente l'interface JsonSerializable et possède une méthode
__toString(), l'objet peut donc être affiché ou utilisé dans les données passées à
json_encode().
echo $url;
echo json_encode([$url]);
Composants de l'URL
Les méthodes suivantes permettent d'obtenir ou de modifier les différents composants de l'URL :
| Setter |
Getter |
Valeur renvoyé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 |
'john:xyz%2A12@nette.org:8080' |
| |
getHostUrl(): string |
'http://john:xyz%2A12@nette.org:8080' |
| |
getAbsoluteUrl(): string |
l'URL entière |
Les méthodes getUser(), getPassword(), setUser() et setPassword() sont
obsolètes, car intégrer des identifiants directement dans une URL est déconseillé.
Attention : lorsque vous travaillez avec une URL obtenue depuis 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 aussi travailler sur les différents paramètres de la query string à l'aide de :
| Setter |
Getter |
setQuery(string|array $query) |
getQueryParameters(): array |
setQueryParameter(string $name, $val) |
getQueryParameter(string $name) |
appendQuery(string|array $query) |
|
getDomain (int $level = 2): string
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) |
'' |
isEqual (string|Url $url): bool
Vérifie si deux URL sont identiques.
$url->isEqual('https://nette.org');
canonicalize()
Convertit l'URL en forme canonique. Cela met le nom d'hôte en minuscules et normalise le chemin (encodage pour cent et
suppression des caractères superflus). La query string reste inchangée.
Url::isAbsolute (string
$url): bool
Vérifie si une URL est absolue. Une URL est considérée comme absolue si elle commence par un schéma (par exemple http,
https, ftp) suivi de deux-points.
Url::isAbsolute('https://nette.org'); // true
Url::isAbsolute('//nette.org'); // false
Url::removeDotSegments (string $path): string
Normalise le chemin d'une URL en supprimant les segments spéciaux . et ... Cette méthode supprime
les éléments de chemin superflus de la même façon que les navigateurs web.
Url::removeDotSegments('/path/../subtree/./file.txt'); // '/subtree/file.txt'
Url::removeDotSegments('/../foo/./bar'); // '/foo/bar'
Url::removeDotSegments('./today/../file.txt'); // 'file.txt'
UrlImmutable
La classe Nette\Http\UrlImmutable est une
alternative immuable à la classe Url (de la même façon que DateTimeImmutable est
l'alternative immuable de DateTime en PHP). Au lieu de setters, elle possède des «withers», qui ne modifient pas
l'objet mais renvoient de nouvelles instances portant la valeur modifiée :
use Nette\Http\UrlImmutable;
$url = new UrlImmutable(
'https://nette.org:8080/en/download?name=param#footer',
);
$newUrl = $url
->withHost('example.com')
->withPath('/en/')
->withQueryParameter('name', 'value');
echo $newUrl; // 'https://example.com:8080/en/?name=value#footer'
La classe UrlImmutable implémente l'interface JsonSerializable et possède une méthode
__toString(), l'objet peut donc être affiché ou utilisé dans les données passées à
json_encode().
echo $url;
echo json_encode([$url]);
Composants de l'URL
Les méthodes suivantes permettent d'obtenir ou de changer les différents composants de l'URL :
| Wither |
Getter |
Valeur renvoyé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 |
'john:xyz%2A12@nette.org:8080' |
| |
getHostUrl(): string |
'http://john:xyz%2A12@nette.org:8080' |
| |
getAbsoluteUrl(): string |
l'URL entière |
Les méthodes getUser(), getPassword(), withUser(), withPassword() et
withoutUserInfo() sont obsolètes, car intégrer des identifiants directement dans une URL est déconseillé.
Nous pouvons aussi travailler sur les différents paramètres de la query string à l'aide de :
| Wither |
Getter |
withQuery(string|array $query) |
getQueryParameters(): array |
withQueryParameter(string $name, $val) |
getQueryParameter(string $name) |
getDomain (int $level = 2): string
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) |
'' |
resolve (string
$reference): UrlImmutable
Résout une URL absolue de la même façon qu'un navigateur traite les liens d'une page HTML :
- si le lien est une URL absolue (contient un schéma), il est utilisé tel quel
- si le lien commence par
//, seul le schéma de l'URL courante est repris
- si le lien commence par
/, un chemin absolu depuis la racine du domaine est créé
- dans les autres cas, l'URL est construite relativement au chemin courant
$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 $url): bool
Vérifie si deux URL sont identiques.
$url->isEqual('https://nette.org');
UrlScript
La classe Nette\Http\UrlScript est un descendant d'UrlImmutable et l'étend de composants d'URL virtuels supplémentaires, comme le répertoire racine
du projet, etc. Comme sa classe parente, c'est un objet immuable.
Le schéma suivant montre les composants que reconnaît UrlScript :
baseUrl basePath relativePath relativeUrl
| | | |
/---------------/-----\/--------\---------------------------\
http://nette.org/admin/script.php/pathinfo/?name=param#footer
\_______________/\________/
| |
scriptPath pathInfo
baseUrl est l'URL de base de l'application, domaine compris, jusqu'au répertoire racine de l'application
basePath est la partie chemin menant au répertoire racine de l'application
scriptPath est le chemin du script courant
relativePath est le nom du script (et éventuellement d'autres segments de chemin) relativement à
basePath
relativeUrl est toute la partie de l'URL située après baseUrl, query string et fragment
compris
pathInfo est une partie de l'URL, aujourd'hui rarement utilisée, située après le nom du script
Les méthodes suivantes permettent d'obtenir ces parties de l'URL :
| Getter |
Valeur renvoyée |
getScriptPath(): string |
'/admin/script.php' |
getBasePath(): string |
'/admin/' |
getBaseUrl(): string |
'http://nette.org/admin/' |
getRelativePath(): string |
'script.php/pathinfo/' |
getRelativeUrl(): string |
'script.php/pathinfo/?name=param#footer' |
getPathInfo(): string |
'/pathinfo/' |
Nous ne créons généralement pas les objets UrlScript directement ; c'est la méthode Nette\Http\Request::getUrl() qui le renvoie, avec les composants déjà
correctement renseignés pour la requête HTTP courante.