Utilité de l'URL

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

→ Installation et exigences

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',
);

La classe Url implémente l'interface JsonSerializable et fournit la méthode __toString(), ce qui permet d'imprimer l'objet ou de l'utiliser avec json_encode().

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

URL Components

Les méthodes suivantes permettent d'obtenir ou de modifier des composants URL individuels :

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 :

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

Vérifie si deux URL sont identiques.

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

Url::isAbsolute (string $url): bool

Vérifie si un URL est absolu. 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 un chemin d'accès URL en supprimant les segments spéciaux . et ... Cette méthode supprime les éléments redondants du chemin d'accès de la même manière que le font les navigateurs.

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 manière que DateTimeImmutable est une alternative immuable à DateTime en PHP). Au lieu de setters, elle a des withers, qui ne modifient pas l'objet mais renvoient 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 fournit la méthode __toString(), ce qui vous permet d'imprimer l'objet ou de l'utiliser avec json_encode().

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

URL Components

Les méthodes suivantes permettent d'obtenir ou de modifier des composants URL individuels :

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

Nous pouvons également utiliser des paramètres de requête individuels à l'aide de la méthode :

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 manière qu'un navigateur traite les liens sur une page HTML :

• Si le lien est une URL absolue (contenant un schéma), il est utilisé tel quel.
• Si le lien commence par //, seul le schéma de l'URL actuelle est appliqué.
• Si le lien commence par /, un chemin absolu à partir de la racine du domaine est créé.
• Dans les autres cas, l'URL est construite par rapport 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 des composants URL virtuels supplémentaires, tels que le répertoire racine du projet, etc. Comme sa classe mère, elle est un objet immuable.

Le diagramme suivant montre les composants reconnus par 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, y compris le domaine et une partie du chemin d'accès au répertoire racine de l'application.
• basePath est une partie du chemin d'accès au répertoire racine de l'application
• scriptPath est le chemin d'accès au script actuel
• relativePath est le nom du script (et éventuellement des segments de chemin supplémentaires) par rapport à 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 désormais rarement utilisée après le nom du script.

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

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