Kit UrlParser
Version 2.2.0
UrlParser est une bibliothèque PHP qui fournit un analyseur d'URL conforme à la RFC 3986 et un composant URI compatible PSR-7. Le but de cette bibliothèque est de fournir un analyseur qui implémente avec précision la spécification RFC contrairement à la fonction intégrée parse_url() , qui diffère de la spécification de manière subtile.
Cette bibliothèque a deux objectifs principaux. Le premier à fournir des informations à partir des URL analysées. Pour y parvenir, la bibliothèque implémente l'interface de gestion d'URI standard du PSR-7 et fournit également des méthodes supplémentaires qui facilitent la récupération des informations couramment utilisées à partir des URL. Le deuxième objectif est de permettre également la modification desdites URL en utilisant l'interface de la norme PSR-7 en plus de quelques méthodes supplémentaires qui simplifient certaines tâches.
Bien que cette bibliothèque soit principalement destinée à l'analyse des URL, l'analyse est simplement basée sur la syntaxe générique des URI. Ainsi, il est possible d'utiliser cette bibliothèque pour valider et analyser tout autre type d'URI par rapport à la syntaxe générique. La bibliothèque n'effectue aucune validation spécifique au schéma pour les URL.
En plus du mode par défaut conforme à la RFC 3986, la bibliothèque propose également des options qui permettent d'analyser les URL contenant des caractères UTF-8 dans différents composants de l'URL tout en les convertissant aux formats ASCII et IDN codés en pourcentage appropriés.
La documentation de l'API est disponible sur : http://kit.riimu.net/api/urlparser/
^1.0 )intl (uniquement prise en charge IDN requise) Le moyen le plus simple d'installer cette bibliothèque consiste à utiliser Composer pour gérer vos dépendances. Afin d'installer cette bibliothèque via Composer, suivez simplement ces deux étapes :
Acquérez le composer.phar en exécutant l’installation en ligne de commande Composer à la racine de votre projet.
Une fois que vous avez exécuté le script d'installation, vous devriez avoir le fichier composer.phar à la racine de votre projet et vous pouvez exécuter la commande suivante :
php composer.phar require "riimu/kit-urlparser:^2.1"
Après avoir installé cette bibliothèque via Composer, vous pouvez charger la bibliothèque en incluant le fichier vendor/autoload.php généré par Composer lors de l'installation.
Si vous savez déjà comment utiliser Composer, vous pouvez également ajouter la bibliothèque en tant que dépendance en ajoutant le fichier composer.json suivant à votre projet et en exécutant la commande composer install :
{
"require" : {
"riimu/kit-urlparser" : " ^2.1 "
}
} Si vous ne souhaitez pas utiliser Composer pour charger la bibliothèque, vous pouvez également télécharger la bibliothèque manuellement en téléchargeant la dernière version et en extrayant le dossier src dans votre projet. Vous pouvez ensuite inclure le fichier src/autoload.php fourni pour charger les classes de la bibliothèque.
Veuillez noter que l'utilisation de Composer téléchargera également automatiquement les autres bibliothèques PHP requises. Si vous installez cette bibliothèque manuellement, vous devrez également rendre disponibles les autres bibliothèques requises.
L'utilisation de cette bibliothèque est relativement simple. La bibliothèque fournit une classe d'analyse d'URL UriParser et une classe d'objets à valeur immuable Uri qui représente l'URL. Pour analyser une URL, vous pouvez simplement fournir l'URL sous forme de chaîne à la méthode parse() dans UriParser qui renvoie une instance d' Uri générée à partir de l'URL analysée.
Par exemple:
<?php
require ' vendor/autoload.php ' ;
$ parser = new Riimu Kit UrlParser UriParser ();
$ uri = $ parser -> parse ( ' http://www.example.com ' );
echo $ uri -> getHost (); // Outputs 'www.example.com' Alternativement, vous pouvez simplement ignorer complètement l'utilisation de UriParser et simplement fournir l'URL en tant que paramètre de constructeur à l' Uri :
<?php
require ' vendor/autoload.php ' ;
$ uri = new Riimu Kit UrlParser Uri ( ' http://www.example.com ' );
echo $ uri -> getHost (); // Outputs 'www.example.com' La principale différence entre l'utilisation de la méthode parse() et celle du constructeur est que la méthode parse() renverra une null si l'URL fournie n'est pas une URL valide, tandis que le constructeur lèvera une InvalidArgumentException .
Pour récupérer différents types d'informations à partir de l'URL, la classe Uri propose différentes méthodes pour vous aider. Voici un exemple simple pour donner un aperçu des différentes méthodes disponibles :
<?php
require ' vendor/autoload.php ' ;
$ parser = new Riimu Kit UrlParser UriParser ();
$ uri = $ parser -> parse ( ' http://jane:[email protected]:8080/site/index.php?action=login&prev=index#form ' );
echo $ uri -> getScheme () . PHP_EOL ; // outputs: http
echo $ uri -> getUsername () . PHP_EOL ; // outputs: jane
echo $ uri -> getPassword () . PHP_EOL ; // outputs: pass123
echo $ uri -> getHost () . PHP_EOL ; // outputs: www.example.com
echo $ uri -> getTopLevelDomain () . PHP_EOL ; // outputs: com
echo $ uri -> getPort () . PHP_EOL ; // outputs: 8080
echo $ uri -> getStandardPort () . PHP_EOL ; // outputs: 80
echo $ uri -> getPath () . PHP_EOL ; // outputs: /site/index.php
echo $ uri -> getPathExtension () . PHP_EOL ; // outputs: php
echo $ uri -> getQuery () . PHP_EOL ; // outputs: action=login&prev=index
echo $ uri -> getFragment () . PHP_EOL ; // outputs: form
print_r ( $ uri -> getPathSegments ()); // [0 => 'site', 1 => 'index.php']
print_r ( $ uri -> getQueryParameters ()); // ['action' => 'login', 'prev' => 'index'] Le composant Uri fournit également diverses méthodes pour modifier l'URL, ce qui vous permet de créer de nouvelles URL à partir de composants distincts ou de modifier celles existantes. Notez que le composant Uri est un objet à valeur immuable, ce qui signifie que chacune des méthodes de modification renvoie une nouvelle instance Uri au lieu de modifier celle existante. Voici un exemple simple de construction d'une URL à partir de ses composants :
<?php
require ' vendor/autoload.php ' ;
$ uri = ( new Riimu Kit UrlParser Uri ())
-> withScheme ( ' http ' )
-> withUserInfo ( ' jane ' , ' pass123 ' )
-> withHost ( ' www.example.com ' )
-> withPort ( 8080 )
-> withPath ( ' /site/index.php ' )
-> withQueryParameters ([ ' action ' => ' login ' , ' prev ' => ' index ' ])
-> withFragment ( ' form ' );
// Outputs: http://jane:[email protected]:8080/site/index.php?action=login&prev=index#form
echo $ uri ; Comme le montre l'exemple précédent, le composant Uri fournit également une méthode __toString() qui fournit l'URL sous forme de chaîne.
Voici la liste des méthodes fournies par le composant Uri pour récupérer des informations à partir de l'URL :
getScheme() renvoie le schéma de l'URL ou une chaîne vide si l'URL n'a pas de schéma.
getAuthority() renvoie le composant de l'URL composé du nom d'utilisateur, du mot de passe, du nom d'hôte et du port au format user-info@hostname:port
getUserInfo() renvoie le composant de l'URL qui contient le nom d'utilisateur et le mot de passe séparés par deux points.
getUsername() renvoie le nom d'utilisateur décodé à partir de l'URL ou une chaîne vide si aucun nom d'utilisateur n'est présent dans l'URL.
getPassword() renvoie le mot de passe décodé de l'URL ou une chaîne vide si aucun mot de passe n'est présent dans l'URL.
getHost() renvoie le nom d'hôte de l'URL ou une chaîne vide si l'URL n'a pas d'hôte.
getIpAddress() renvoie l'adresse IP de l'hôte, si l'hôte est une adresse IP. Sinon, cette méthode renverra null . Si une adresse IPv6 a été fournie, l'adresse est renvoyée sans les accolades environnantes.
getTopLevelDomain() renvoie le domaine de premier niveau de l'hôte. S'il n'y a pas d'hôte ou si l'hôte est une adresse IP, une chaîne vide sera renvoyée à la place.
getPort() renvoie le port de l'URL ou une null s'il n'y a aucun port présent dans l'URL. Cette méthode renverra également une null si le port est le port standard du schéma actuel (par exemple 80 pour http).
getStandardPort() renvoie le port standard du schéma actuel. S'il n'y a pas de schéma ou si le port standard du schéma n'est pas connu, une null sera renvoyée à la place.
getPath() renvoie le chemin de l'URL ou une chaîne vide si l'URL n'a pas de chemin.
getPathSegments() renvoie un tableau de segments de chemin décodés (c'est-à-dire le chemin divisé par chaque barre oblique). Les segments de chemin vides sont ignorés et ne sont pas inclus dans le tableau renvoyé.
getPathExtension() renvoie l'extension de fichier à partir du chemin ou une chaîne vide si l'URL n'a pas de chemin.
getQuery() renvoie la chaîne de requête de l'URL ou une chaîne vide si l'URL n'a pas de chaîne de requête.
getQueryParameters() analyse la chaîne de requête de l'URL à l'aide de la fonction parse_str() et renvoie le tableau de valeurs analysées.
getFragment() renvoie le fragment de l'URL ou une chaîne vide si l'URL n'a pas de fragment.
__toString() renvoie l'URL sous forme de chaîne.
Le composant Uri fournit diverses méthodes qui peuvent être utilisées pour modifier les URL et en construire de nouvelles. Notez que puisque la classe Uri est un objet à valeur immuable, chaque méthode renvoie une nouvelle instance d' Uri plutôt que de modifier celle existante.
withScheme($scheme) renvoie une nouvelle instance avec le schéma donné. Un schéma vide peut être utilisé pour supprimer le schéma de l'URL. Notez que tout schéma fourni est normalisé en minuscules.
withUserInfo($user, $password = null) renvoie une nouvelle instance avec le nom d'utilisateur et le mot de passe donnés. Notez que le mot de passe est ignoré sauf si un nom d'utilisateur est fourni. Un nom d'utilisateur vide peut être utilisé pour supprimer le nom d'utilisateur et le mot de passe de l'URL. Tout caractère qui ne peut pas être inséré seul dans l’URL sera codé en pourcentage.
withHost($host) renvoie une nouvelle instance avec l'hôte donné. Un hôte vide peut être utilisé pour supprimer l'hôte de l'URL. Notez que cette méthode n'accepte pas les noms de domaine internationaux. Notez que cette méthode normalisera également l'hôte en minuscules.
withPort($port) renvoie une nouvelle instance avec le port donné. Un null peut être utilisé pour supprimer le port de l'URL.
withPath($path) renvoie une nouvelle instance avec le chemin donné. Un chemin vide peut être utilisé pour supprimer le chemin de l'URL. Notez que tout caractère qui n'est pas un caractère de chemin valide sera codé en pourcentage dans l'URL. Toutefois, les caractères codés en pourcentage existants ne seront pas codés deux fois.
withPathSegments(array $segments) renvoie une nouvelle instance avec le chemin construit à partir du tableau de segments de chemin. Tous les caractères de chemin non valides dans les segments seront codés en pourcentage, y compris la barre oblique et les caractères codés en pourcentage existants.
withQuery($query) renvoie une nouvelle instance avec la chaîne de requête donnée. Une chaîne de requête vide peut être utilisée pour supprimer le chemin de l'URL. Notez que tout caractère qui n’est pas un caractère de chaîne de requête valide sera codé en pourcentage dans l’URL. Toutefois, les caractères codés en pourcentage existants ne seront pas codés deux fois.
withQueryParameters(array $parameters) renvoie une nouvelle instance avec la chaîne de requête construite à partir des paramètres fournis à l'aide de la fonction http_build_query() . Tous les caractères de chaîne de requête non valides dans les paramètres seront codés en pourcentage, y compris l'esperluette, le signe égal et les caractères codés en pourcentage existants.
withFragment($fragment) renvoie une nouvelle instance avec le fragment donné. Une chaîne vide peut être utilisée pour supprimer le fragment de l'URL. Notez que tout caractère qui n'est pas un caractère de fragment valide sera codé en pourcentage dans l'URL. Toutefois, les caractères codés en pourcentage existants ne seront pas codés deux fois.
Par défaut, cette bibliothèque fournit un analyseur conforme à la RFC 3986. La spécification RFC n'autorise pas l'utilisation de caractères UTF-8 dans le nom de domaine ou dans toute autre partie de l'URL. La représentation correcte de ceux-ci dans l'URL consiste à utiliser une norme IDN pour les noms de domaine et le pourcentage de codage des caractères UTF-8 dans d'autres parties.
Cependant, pour vous aider à gérer les caractères codés en UTF-8, de nombreuses méthodes du composant Uri encoderont automatiquement en pourcentage tous les caractères qui ne peuvent pas être insérés seuls dans l'URL, y compris les caractères UTF-8. Cependant, en raison des complexités impliquées, la méthode withHost() n'autorise pas les caractères codés en UTF-8.
Par défaut, l'analyseur n'analyse pas non plus les URL contenant des caractères codés en UTF-8, car cela serait contraire à la spécification RFC. Cependant, l'analyseur fournit deux modes d'analyse supplémentaires qui autorisent ces caractères autant que possible.
Si vous souhaitez analyser des URL susceptibles de contenir des caractères UTF-8 dans les informations utilisateur (c'est-à-dire le nom d'utilisateur ou le mot de passe), le chemin, la requête ou le fragment des composants de l'URL, vous pouvez simplement utiliser le mode d'analyse UTF-8. Par exemple:
<?php
require ' vendor/autoload.php ' ;
$ parser = new Riimu Kit UrlParser UriParser ();
$ parser -> setMode ( Riimu Kit UrlParser UriParser:: MODE_UTF8 );
$ uri = $ parser -> parse ( ' http://www.example.com/föö/bär.html ' );
echo $ uri -> getPath (); // Outputs: /f%C3%B6%C3%B6/b%C3%A4r.htmlLes caractères UTF-8 dans le nom de domaine constituent cependant un problème un peu plus complexe. L'analyseur fournit cependant un support rudimentaire pour analyser ces noms de domaine en utilisant le mode IDNA. Par exemple:
<?php
require ' vendor/autoload.php ' ;
$ parser = new Riimu Kit UrlParser UriParser ();
$ parser -> setMode ( Riimu Kit UrlParser UriParser:: MODE_IDNA );
$ uri = $ parser -> parse ( ' http://www.fööbär.com ' );
echo $ uri -> getHost (); // Outputs: www.xn--fbr-rla2ga.com Notez que l'utilisation de ce mode d'analyse nécessite que l'extension PHP intl soit activée. Le mode d'analyse approprié peut également être fourni au constructeur du composant Uri à l'aide du deuxième paramètre du constructeur.
Bien que la prise en charge de l'analyse de ces caractères UTF-8 soit disponible, cette bibliothèque ne fournit aucune méthode pour les opérations inverses puisque le but de cette bibliothèque est de traiter les URI conformes à la RFC 3986.
Étant donné que la spécification RFC 3986 définit certaines URL comme équivalentes malgré quelques légères différences, cette bibliothèque effectue une normalisation minimale des valeurs fournies. Vous pouvez rencontrer ces cas lors de l'analyse, par exemple, des URL fournies par les utilisateurs. Les normalisations les plus notables que vous pouvez rencontrer sont les suivantes :
scheme et les composants host sont considérés comme insensibles à la casse. Ainsi, ces composants seront toujours normalisés en minuscules.getAuthority() et __toString() si le port est le port standard du schéma actuel.__toString() peut changer selon que l'URL comporte ou non un composant authority .userinfo peut différer en raison du fait que UriParser fonctionne avec la spécification PSR-7 qui ne fournit pas de moyen de fournir un nom d'utilisateur ou un mot de passe codé. Cette bibliothèque est protégée par Copyright (c) 2013-2022 Riikka Kalliomäki.
Voir LICENCE pour les informations sur la licence et la copie.
