Kit UrlParser
Version 2.2.0
UrlParser é uma biblioteca PHP que fornece um analisador de URL compatível com RFC 3986 e um componente URI compatível com PSR-7. O objetivo desta biblioteca é fornecer um analisador que implemente com precisão a especificação RFC, ao contrário da função integrada parse_url() , que difere da especificação de algumas maneiras sutis.
Esta biblioteca tem dois propósitos principais. O primeiro a fornecer informações dos URLs analisados. Para conseguir isso, a biblioteca implementa a interface de manipulação de URI padrão do PSR-7 e também fornece métodos adicionais que facilitam a recuperação de informações comumente usadas dos URLs. O segundo objetivo é permitir também a modificação das referidas URLs utilizando a interface do padrão PSR-7 além de alguns métodos extras que tornam algumas tarefas mais simples.
Embora esta biblioteca seja destinada principalmente à análise de URLs, a análise é simplesmente baseada na sintaxe genérica do URI. Assim, é possível utilizar esta biblioteca para validar e analisar quaisquer outros tipos de URIs em relação à sintaxe genérica. A biblioteca não realiza nenhuma validação específica de esquema para as URLs.
Além do modo padrão compatível com RFC 3986, a biblioteca também oferece opções que permitem a análise de URLs que contêm caracteres UTF-8 em diferentes componentes do URL, convertendo-os para os formatos ASCII e IDN codificados por porcentagem apropriados.
A documentação da API está disponível em: http://kit.riimu.net/api/urlparser/
^1.0 )intl (só é necessário suporte a IDN) A maneira mais fácil de instalar esta biblioteca é usar o Composer para lidar com suas dependências. Para instalar esta biblioteca via Composer, basta seguir estes dois passos:
Adquira o composer.phar executando a instalação da linha de comando do Composer na raiz do seu projeto.
Depois de executar o script de instalação, você deverá ter o arquivo composer.phar na raiz do projeto e poderá executar o seguinte comando:
php composer.phar require "riimu/kit-urlparser:^2.1"
Após instalar esta biblioteca via Composer, você pode carregá-la incluindo o arquivo vendor/autoload.php que foi gerado pelo Composer durante a instalação.
Se você já está familiarizado com o uso do Composer, você pode alternativamente adicionar a biblioteca como uma dependência adicionando o seguinte arquivo composer.json ao seu projeto e executando o comando composer install :
{
"require" : {
"riimu/kit-urlparser" : " ^2.1 "
}
} Se não desejar usar o Composer para carregar a biblioteca, você também pode fazer o download da biblioteca manualmente, baixando a versão mais recente e extraindo a pasta src para o seu projeto. Você pode então incluir o arquivo src/autoload.php fornecido para carregar as classes da biblioteca.
Observe que usar o Composer também baixará automaticamente as outras bibliotecas PHP necessárias. Se você instalar esta biblioteca manualmente, também precisará disponibilizar as outras bibliotecas necessárias.
Usar esta biblioteca é relativamente simples. A biblioteca fornece uma classe de análise de URL UriParser e uma classe de objeto de valor imutável Uri que representa a URL. Para analisar uma URL, você pode simplesmente fornecer a URL como uma string para o método parse() em UriParser , que retorna uma instância de Uri que foi gerada a partir da URL analisada.
Por exemplo:
<?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, você pode simplesmente pular completamente o UriParser e simplesmente fornecer a URL como um parâmetro de construtor para o Uri :
<?php
require ' vendor/autoload.php ' ;
$ uri = new Riimu Kit UrlParser Uri ( ' http://www.example.com ' );
echo $ uri -> getHost (); // Outputs 'www.example.com' A principal diferença entre usar o método parse() e o construtor é que o método parse() retornará um null se o URL fornecido não for um URL válido, enquanto o construtor lançará um InvalidArgumentException .
Para recuperar diferentes tipos de informações da URL, a classe Uri fornece vários métodos diferentes para ajudá-lo. Aqui está um exemplo simples como uma visão geral dos diferentes métodos disponíveis:
<?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'] O componente Uri também fornece vários métodos para modificar a URL, o que permite construir novas URLs a partir de componentes separados ou modificar as existentes. Observe que o componente Uri é um objeto de valor imutável, o que significa que cada um dos métodos modificadores retorna uma nova instância Uri em vez de modificar a existente. Aqui está um exemplo simples de construção de uma URL a partir de seus 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 pode ser visto no exemplo anterior, o componente Uri também fornece um método __toString() que fornece a URL como uma string.
Aqui está a lista de métodos que o componente Uri fornece para recuperar informações da URL:
getScheme() retorna o esquema da URL ou uma string vazia se a URL não tiver esquema.
getAuthority() retorna o componente da URL que consiste no nome de usuário, senha, nome do host e porta no formato user-info@hostname:port
getUserInfo() retorna o componente da URL que contém o nome de usuário e a senha separados por dois pontos.
getUsername() retorna o nome de usuário decodificado do URL ou uma string vazia se não houver nenhum nome de usuário presente no URL.
getPassword() retorna a senha decodificada da URL ou uma string vazia se não houver senha presente na URL.
getHost() retorna o nome do host da URL ou uma string vazia se a URL não tiver host.
getIpAddress() retorna o endereço IP do host, se o host for um endereço IP. Caso contrário, este método retornará null . Se um endereço IPv6 foi fornecido, o endereço será retornado sem os colchetes.
getTopLevelDomain() retorna o domínio de nível superior do host. Se não houver nenhum host ou se o host for um endereço IP, uma string vazia será retornada.
getPort() retorna a porta da URL ou um null se não houver porta presente na URL. Este método também retornará null se a porta for a porta padrão para o esquema atual (por exemplo, 80 para http).
getStandardPort() retorna a porta padrão para o esquema atual. Se não houver nenhum esquema ou a porta padrão do esquema não for conhecida, um null será retornado.
getPath() retorna o caminho da URL ou uma string vazia se a URL não tiver caminho.
getPathSegments() retorna uma matriz de segmentos de caminho decodificados (ou seja, o caminho dividido por cada barra). Segmentos de caminho vazios são descartados e não incluídos na matriz retornada.
getPathExtension() retorna a extensão do arquivo do caminho ou uma string vazia se o URL não tiver caminho.
getQuery() retorna a string de consulta do URL ou uma string vazia se o URL não tiver string de consulta.
getQueryParameters() analisa a string de consulta do URL usando a função parse_str() e retorna a matriz de valores analisados.
getFragment() retorna o fragmento da URL ou uma string vazia se a URL não tiver nenhum fragmento.
__toString() retorna a URL como uma string.
O componente Uri fornece vários métodos que podem ser usados para modificar URLs e construir novos. Observe que como a classe Uri é um objeto de valor imutável, cada método retorna uma nova instância de Uri em vez de modificar a existente.
withScheme($scheme) retorna uma nova instância com o esquema fornecido. Um esquema vazio pode ser usado para remover o esquema do URL. Observe que qualquer esquema fornecido é normalizado para letras minúsculas.
withUserInfo($user, $password = null) retorna uma nova instância com o nome de usuário e senha fornecidos. Observe que a senha é ignorada, a menos que um nome de usuário seja fornecido. Nome de usuário vazio pode ser usado para remover o nome de usuário e a senha do URL. Qualquer caractere que não possa ser inserido sozinho no URL será codificado em porcentagem.
withHost($host) retorna uma nova instância com o host fornecido. Um host vazio pode ser usado para remover o host da URL. Observe que este método não aceita nomes de domínio internacionais. Observe que este método também normalizará o host para letras minúsculas.
withPort($port) retorna uma nova instância com a porta fornecida. Um null pode ser usado para remover a porta da URL.
withPath($path) retorna uma nova instância com o caminho fornecido. Um caminho vazio pode ser usado para remover o caminho da URL. Observe que qualquer caractere que não seja um caractere de caminho válido será codificado em porcentagem no URL. Entretanto, os caracteres codificados por porcentagem existentes não serão codificados duplamente.
withPathSegments(array $segments) retorna uma nova instância com o caminho construído a partir da matriz de segmentos de caminho. Todos os caracteres de caminho inválidos nos segmentos serão codificados em porcentagem, incluindo a barra e os caracteres codificados em porcentagem existentes.
withQuery($query) retorna uma nova instância com a string de consulta fornecida. Uma string de consulta vazia pode ser usada para remover o caminho do URL. Observe que qualquer caractere que não seja um caractere de string de consulta válido será codificado em porcentagem no URL. Entretanto, os caracteres codificados por porcentagem existentes não serão codificados duplamente.
withQueryParameters(array $parameters) retorna uma nova instância com a string de consulta construída a partir dos parâmetros fornecidos usando a função http_build_query() . Todos os caracteres de string de consulta inválidos nos parâmetros serão codificados em porcentagem, incluindo o "e" comercial, o sinal de igual e os caracteres codificados em porcentagem existentes.
withFragment($fragment) retorna uma nova instância com o fragmento fornecido. Uma string vazia pode ser usada para remover o fragmento da URL. Observe que qualquer caractere que não seja um caractere de fragmento válido será codificado em porcentagem no URL. Entretanto, os caracteres codificados por porcentagem existentes não serão codificados duplamente.
Por padrão, esta biblioteca fornece um analisador compatível com RFC 3986. A especificação RFC não permite o uso de caracteres UTF-8 no nome de domínio ou em qualquer outra parte do URL. A representação correta para eles no URL é usar um padrão IDN para nomes de domínio e codificação percentual dos caracteres UTF-8 em outras partes.
No entanto, para ajudá-lo a lidar com caracteres codificados em UTF-8, muitos dos métodos no componente Uri codificarão automaticamente por cento quaisquer caracteres que não possam ser inseridos no URL por conta própria, incluindo caracteres UTF-8. Devido às complexidades envolvidas, entretanto, o método withHost() não permite caracteres codificados em UTF-8.
Por padrão, o analisador também não analisa URLs que incluam caracteres codificados em UTF-8 porque isso seria contrário à especificação RFC. No entanto, o analisador fornece dois modos de análise adicionais que permitem esses caracteres sempre que possível.
Se você deseja analisar URLs que podem conter caracteres UTF-8 nas informações do usuário (ou seja, nome de usuário ou senha), caminho, consulta ou componentes de fragmento da URL, você pode simplesmente usar o modo de análise UTF-8. Por exemplo:
<?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.htmlCaracteres UTF-8 no nome de domínio, entretanto, são um problema um pouco mais complexo. O analisador, entretanto, fornece suporte rudimentar para analisar esses nomes de domínio usando o modo IDNA. Por exemplo:
<?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 Observe que o uso deste modo de análise requer que a extensão intl do PHP esteja habilitada. O modo de análise apropriado também pode ser fornecido ao construtor do componente Uri usando o segundo parâmetro do construtor.
Embora o suporte para análise desses caracteres UTF-8 esteja disponível, esta biblioteca não fornece nenhum método para operações reversas, uma vez que o objetivo desta biblioteca é lidar com URIs compatíveis com RFC 3986.
Devido ao fato de que a especificação RFC 3986 define alguns URLs como equivalentes, apesar de terem algumas pequenas diferenças, esta biblioteca faz uma normalização mínima para os valores fornecidos. Você pode encontrar essas instâncias ao, por exemplo, analisar URLs fornecidos pelos usuários. As normalizações mais notáveis que você pode encontrar são as seguintes:
scheme e os componentes host não diferenciam maiúsculas de minúsculas. Assim, esses componentes serão sempre normalizados para letras minúsculas.getAuthority() e __toString() se a porta for a porta padrão para o esquema atual.__toString() pode mudar dependendo se a URL possui um componente authority ou não.userinfo pode diferir devido ao fato de que o UriParser funciona com a especificação PSR-7, que não fornece uma maneira de fornecer nome de usuário ou senha codificados. Esta biblioteca tem Copyright (c) 2013-2022 Riikka Kalliomäki.
Consulte LICENÇA para obter informações sobre licença e cópia.
