Travailler avec les URL

Les classes Url, UrlImmutable et UrlScript permettent de générer, parser et manipuler facilement les URL.

→ Installation et prérequis

Url

La classe Nette\Http\Url permet de travailler facilement avec les URL et leurs différentes composantes, illustrées par 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

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'

Il est également possible de parser une URL et de la manipuler ensuite :

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

La classe Url implémente l'interface JsonSerializable et a une méthode __toString(), de sorte que l'objet peut être affiché ou utilisé dans des données passées à json_encode().

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

Composantes de l'URL

Pour retourner ou modifier les différentes composantes de l'URL, les méthodes suivantes sont à votre disposition :

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 travailler avec les paramètres de requête individuels en utilisant :

getDomain (int $level = 2): string

Retourne la partie droite ou gauche de l'hôte. Voici comment cela fonctionne si l'hôte est www.nette.org :

isEqual (string|Url $anotherUrl): bool

Vérifie si deux URL sont identiques.

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

Url::isAbsolute (string $url): bool

Vérifie si l'URL est absolue. Une URL est considérée comme absolue si elle commence par un schéma (par ex. 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 dans l'URL en supprimant les segments spéciaux . et ... La méthode supprime les éléments de chemin superflus de la même manière que le font 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 immutable (immuable) à la classe Url (similaire à la façon dont DateTimeImmutable en PHP est une alternative immuable à DateTime). Au lieu de setters, elle a des withers, qui ne modifient pas l'objet, mais retournent de nouvelles instances avec la 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'

La classe UrlImmutable implémente l'interface JsonSerializable et a une méthode __toString(), de sorte que l'objet peut être affiché ou utilisé dans des données passées à json_encode().

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

Composantes de l'URL

Pour retourner ou modifier les différentes composantes de l'URL, les méthodes suivantes sont utilisées :

La méthode withoutUserInfo() supprime user et password.

Nous pouvons également travailler avec les paramètres de requête individuels en utilisant :

getDomain (int $level = 2): string

Retourne la partie droite ou gauche de l'hôte. Voici comment cela fonctionne si l'hôte est www.nette.org :

resolve (string $reference): UrlImmutable

Dérive une URL absolue de la même manière qu'un navigateur traite les liens sur 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 actuelle est repris
• si le lien commence par /, un chemin absolu est créé à partir de la racine du domaine
• dans les autres cas, l'URL est construite relativement au chemin actuel

$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 $anotherUrl): bool

Vérifie si deux URL sont identiques.

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

UrlScript

La classe Nette\Http\UrlScript est un descendant de UrlImmutable et l'étend avec d'autres composantes URL virtuelles, telles que le répertoire racine du projet, etc. Tout comme la classe parente, c'est un objet immutable (immuable).

Le diagramme suivant illustre les composantes que UrlScript reconnaît :

     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, y compris le domaine et la partie du chemin vers le répertoire racine de l'application
• basePath est la partie du chemin vers le répertoire racine de l'application
• scriptPath est le chemin vers le script actuel
• relativePath est le nom du script (éventuellement d'autres segments de chemin) relatif à basePath
• relativeUrl est toute la partie de l'URL après baseUrl, y compris la chaîne de requête et le fragment.
• pathInfo est une partie de l'URL peu utilisée aujourd'hui après le nom du script

Pour retourner les parties de l'URL, les méthodes suivantes sont disponibles :

Les objets UrlScript ne sont généralement pas créés directement, mais sont retournés par la méthode Nette\Http\Request::getUrl() avec les composantes déjà correctement définies pour la requête HTTP actuelle.