Kit UrlParser
Version 2.2.0
UrlParser es una biblioteca PHP que proporciona un analizador de URL compatible con RFC 3986 y un componente de URI compatible con PSR-7. El propósito de esta biblioteca es proporcionar un analizador que implemente con precisión la especificación RFC a diferencia de la función integrada parse_url() , que difiere de la especificación en algunas formas sutiles.
Esta biblioteca tiene dos propósitos principales. El primero en proporcionar información de las URL analizadas. Para lograr esto, la biblioteca implementa la interfaz de manejo de URI estándar del PSR-7 y también proporciona métodos adicionales que facilitan la recuperación de información de uso común de las URL. El segundo objetivo es permitir también la modificación de dichas URL utilizando la interfaz del estándar PSR-7 además de algunos métodos extra que simplifican algunas tareas.
Si bien esta biblioteca está destinada principalmente a analizar URL, el análisis se basa simplemente en la sintaxis genérica de URI. Por lo tanto, es posible utilizar esta biblioteca para validar y analizar cualquier otro tipo de URI con la sintaxis genérica. La biblioteca no realiza ninguna validación específica de esquema para las URL.
Además del modo predeterminado compatible con RFC 3986, la biblioteca también ofrece opciones que permiten analizar URL que contienen caracteres UTF-8 en diferentes componentes de la URL mientras las convierte al porcentaje de codificación apropiado y a los formatos IDN ascii.
La documentación de la API está disponible en: http://kit.riimu.net/api/urlparser/
^1.0 )intl (solo se requiere soporte IDN) La forma más sencilla de instalar esta biblioteca es utilizar Composer para manejar sus dependencias. Para instalar esta biblioteca a través de Composer, simplemente siga estos dos pasos:
Adquiera composer.phar ejecutando la instalación de la línea de comandos de Composer en la raíz de su proyecto.
Una vez que haya ejecutado el script de instalación, debería tener el archivo composer.phar en la raíz de su proyecto y podrá ejecutar el siguiente comando:
php composer.phar require "riimu/kit-urlparser:^2.1"
Después de instalar esta biblioteca a través de Composer, puede cargar la biblioteca incluyendo el archivo vendor/autoload.php que generó Composer durante la instalación.
Si ya está familiarizado con el uso de Composer, también puede agregar la biblioteca como una dependencia agregando el siguiente archivo composer.json a su proyecto y ejecutando el comando composer install :
{
"require" : {
"riimu/kit-urlparser" : " ^2.1 "
}
} Si no desea utilizar Composer para cargar la biblioteca, también puede descargar la biblioteca manualmente descargando la última versión y extrayendo la carpeta src a su proyecto. Luego puede incluir el archivo src/autoload.php proporcionado para cargar las clases de la biblioteca.
Tenga en cuenta que el uso de Composer también descargará automáticamente las otras bibliotecas PHP requeridas. Si instala esta biblioteca manualmente, también deberá poner a disposición las otras bibliotecas requeridas.
Usar esta biblioteca es relativamente sencillo. La biblioteca proporciona una clase de análisis de URL UriParser y una clase de objeto de valor inmutable Uri que representa la URL. Para analizar una URL, simplemente puede proporcionar la URL como una cadena al método parse() en UriParser , que devuelve una instancia de Uri que se generó a partir de la URL analizada.
Por ejemplo:
<?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' Alternativamente, puede simplemente omitir el uso de UriParser por completo y simplemente proporcionar la URL como parámetro de constructor al Uri :
<?php
require ' vendor/autoload.php ' ;
$ uri = new Riimu Kit UrlParser Uri ( ' http://www.example.com ' );
echo $ uri -> getHost (); // Outputs 'www.example.com' La principal diferencia entre usar el método parse() y el constructor es que el método parse() devolverá un null si la URL proporcionada no es una URL válida, mientras que el constructor arrojará una InvalidArgumentException .
Para recuperar diferentes tipos de información de la URL, la clase Uri proporciona varios métodos diferentes para ayudarle. A continuación se muestra un ejemplo sencillo como descripción general de los diferentes métodos 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'] El componente Uri también proporciona varios métodos para modificar la URL, lo que le permite construir nuevas URL a partir de componentes separados o modificar las existentes. Tenga en cuenta que el componente Uri es un objeto de valor inmutable, lo que significa que cada uno de los métodos de modificación devuelve una nueva instancia Uri en lugar de modificar la existente. A continuación se muestra un ejemplo sencillo de cómo construir una URL a partir de sus componentes:
<?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 ; Como se puede ver en el ejemplo anterior, el componente Uri también proporciona un método __toString() que proporciona la URL como una cadena.
Aquí está la lista de métodos que proporciona el componente Uri para recuperar información de la URL:
getScheme() devuelve el esquema de la URL o una cadena vacía si la URL no tiene ningún esquema.
getAuthority() devuelve el componente de la URL que consta del nombre de usuario, contraseña, nombre de host y puerto en el formato user-info@hostname:port
getUserInfo() devuelve el componente de la URL que contiene el nombre de usuario y la contraseña separados por dos puntos.
getUsername() devuelve el nombre de usuario decodificado de la URL o una cadena vacía si no hay ningún nombre de usuario presente en la URL.
getPassword() devuelve la contraseña decodificada de la URL o una cadena vacía si no hay ninguna contraseña en la URL.
getHost() devuelve el nombre de host de la URL o una cadena vacía si la URL no tiene host.
getIpAddress() devuelve la dirección IP del host, si el host es una dirección IP. De lo contrario, este método devolverá null . Si se proporcionó una dirección IPv6, la dirección se devuelve sin las llaves circundantes.
getTopLevelDomain() devuelve el dominio de nivel superior del host. Si no hay ningún host o el host es una dirección IP, se devolverá una cadena vacía.
getPort() devuelve el puerto de la URL o un null si no hay ningún puerto presente en la URL. Este método también devolverá un null si el puerto es el puerto estándar para el esquema actual (por ejemplo, 80 para http).
getStandardPort() devuelve el puerto estándar para el esquema actual. Si no hay ningún esquema o no se conoce el puerto estándar para el esquema, se devolverá un null .
getPath() devuelve la ruta de la URL o una cadena vacía si la URL no tiene ruta.
getPathSegments() devuelve una matriz de segmentos de ruta decodificados (es decir, la ruta dividida por cada barra diagonal). Los segmentos de ruta vacíos se descartan y no se incluyen en la matriz devuelta.
getPathExtension() devuelve la extensión del archivo de la ruta o una cadena vacía si la URL no tiene ruta.
getQuery() devuelve la cadena de consulta de la URL o una cadena vacía si la URL no tiene una cadena de consulta.
getQueryParameters() analiza la cadena de consulta de la URL utilizando la función parse_str() y devuelve la matriz de valores analizados.
getFragment() devuelve el fragmento de la URL o una cadena vacía si la URL no tiene ningún fragmento.
__toString() devuelve la URL como una cadena.
El componente Uri proporciona varios métodos que se pueden utilizar para modificar URL y construir otras nuevas. Tenga en cuenta que, dado que la clase Uri es un objeto de valor inmutable, cada método devuelve una nueva instancia de Uri en lugar de modificar la existente.
withScheme($scheme) devuelve una nueva instancia con el esquema dado. Se puede utilizar un esquema vacío para eliminar el esquema de la URL. Tenga en cuenta que cualquier esquema proporcionado está normalizado a minúsculas.
withUserInfo($user, $password = null) devuelve una nueva instancia con el nombre de usuario y la contraseña proporcionados. Tenga en cuenta que la contraseña se ignora a menos que se proporcione un nombre de usuario. Se puede utilizar un nombre de usuario vacío para eliminar el nombre de usuario y la contraseña de la URL. Cualquier carácter que no pueda insertarse en la URL por sí solo se codificará en porcentaje.
withHost($host) devuelve una nueva instancia con el host dado. Se puede utilizar un host vacío para eliminar el host de la URL. Tenga en cuenta que este método no acepta nombres de dominio internacionales. Tenga en cuenta que este método también normalizará el host a minúsculas.
withPort($port) devuelve una nueva instancia con el puerto dado. Se puede utilizar un null para eliminar el puerto de la URL.
withPath($path) devuelve una nueva instancia con la ruta dada. Se puede utilizar una ruta vacía para eliminar la ruta de la URL. Tenga en cuenta que cualquier carácter que no sea un carácter de ruta válido se codificará en porcentaje en la URL. Sin embargo, los caracteres codificados por porcentaje existentes no tendrán doble codificación.
withPathSegments(array $segments) devuelve una nueva instancia con la ruta construida a partir de la matriz de segmentos de ruta. Todos los caracteres de ruta no válidos en los segmentos se codificarán en porcentaje, incluida la barra diagonal y los caracteres codificados en porcentaje existentes.
withQuery($query) devuelve una nueva instancia con la cadena de consulta proporcionada. Se puede utilizar una cadena de consulta vacía para eliminar la ruta de la URL. Tenga en cuenta que cualquier carácter que no sea un carácter de cadena de consulta válido se codificará en porcentaje en la URL. Sin embargo, los caracteres codificados por porcentaje existentes no tendrán doble codificación.
withQueryParameters(array $parameters) devuelve una nueva instancia con la cadena de consulta construida a partir de los parámetros proporcionados usando la función http_build_query() . Todos los caracteres de cadena de consulta no válidos en los parámetros se codificarán en porcentaje, incluidos el signo comercial, el signo igual y los caracteres codificados en porcentaje existentes.
withFragment($fragment) devuelve una nueva instancia con el fragmento dado. Se puede utilizar una cadena vacía para eliminar el fragmento de la URL. Tenga en cuenta que cualquier carácter que no sea un carácter de fragmento válido se codificará en porcentaje en la URL. Sin embargo, los caracteres codificados por porcentaje existentes no tendrán doble codificación.
De forma predeterminada, esta biblioteca proporciona un analizador que cumple con RFC 3986. La especificación RFC no permite el uso de caracteres UTF-8 en el nombre de dominio ni en ninguna otra parte de la URL. La representación correcta de estos en la URL es utilizar un estándar IDN para nombres de dominio y un porcentaje de codificación de caracteres UTF-8 en otras partes.
Sin embargo, para ayudarle a manejar los caracteres codificados en UTF-8, muchos de los métodos del componente Uri codificarán automáticamente en porcentaje cualquier carácter que no se pueda insertar en la URL por sí solo, incluidos los caracteres UTF-8. Sin embargo, debido a las complejidades involucradas, el método withHost() no permite caracteres codificados en UTF-8.
De forma predeterminada, el analizador tampoco analiza ninguna URL que incluya caracteres codificados en UTF-8 porque eso iría en contra de la especificación RFC. Sin embargo, el analizador proporciona dos modos de análisis adicionales que permiten estos caracteres siempre que sea posible.
Si desea analizar URL que pueden contener caracteres UTF-8 en la información del usuario (es decir, el nombre de usuario o contraseña), ruta, consulta o fragmentos de componentes de la URL, simplemente puede usar el modo de análisis UTF-8. Por ejemplo:
<?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.htmlSin embargo, los caracteres UTF-8 en el nombre de dominio son un tema un poco más complejo. Sin embargo, el analizador proporciona un soporte rudimentario para analizar estos nombres de dominio utilizando el modo IDNA. Por ejemplo:
<?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 Tenga en cuenta que el uso de este modo de análisis requiere que la extensión PHP intl esté habilitada. El modo de análisis apropiado también se puede proporcionar al constructor del componente Uri utilizando el segundo parámetro del constructor.
Si bien está disponible el soporte para analizar estos caracteres UTF-8, esta biblioteca no proporciona ningún método para las operaciones inversas, ya que el propósito de esta biblioteca es tratar con URI compatibles con RFC 3986.
Debido al hecho de que la especificación RFC 3986 define algunas URL como equivalentes a pesar de tener algunas diferencias leves, esta biblioteca realiza una normalización mínima de los valores proporcionados. Puede encontrar estos casos cuando, por ejemplo, analiza las URL proporcionadas por los usuarios. Las normalizaciones más notables que puede encontrar son las siguientes:
scheme y los componentes host no distinguen entre mayúsculas y minúsculas. Por lo tanto, estos componentes siempre estarán normalizados a minúsculas.getAuthority() y __toString() si el puerto es el puerto estándar para el esquema actual.__toString() puede cambiar dependiendo de si la URL tiene un componente authority o no.userinfo puede diferir debido al hecho de que UriParser funciona con la especificación PSR-7, que no proporciona una forma de proporcionar un nombre de usuario o contraseña codificados. Esta biblioteca tiene Copyright (c) 2013-2022 Riikka Kalliomäki.
Consulte LICENCIA para obtener información sobre licencias y copias.
