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 :

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 :

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 :

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 :

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 :

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 :

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 :

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.