parse_url
(PHP 4, PHP 5, PHP 7, PHP 8)
parse_url — Analisa uma URL e retorna seus componentes
Descrição
Esta função não se destina a validar
o URL fornecido, apenas o divide nas partes listadas abaixo. URLs parciais e inválidos
também são aceitos. parse_url() faz o possível para
analisá-los corretamente.
Cuidado
Esta função não segue nenhum padrão estabelecido de URI ou URL.
Ela retornará resultados incorretos ou sem sentido para URLs relativas ou
malformadas. Mesmo para URLs válidas, o resultado pode diferir do de um
analisador de URL diferente, já que existem vários padrões diferentes relacionados
a URLs que visam casos de uso diferentes e que diferem em seus
requisitos.
O processamento de uma URL com analisadores que seguem diferentes padrões de URL é uma
fonte comum de vulnerabilidades de segurança. Por exemplo, validar
uma URL em relação a uma lista de permissões de nomes de host aceitáveis com o analisador A
pode ser ineficaz quando a recuperação real do recurso usa
o analisador B que extrai os nomes de host de forma diferente.
As classes Uri\Rfc3986\Uri e Uri\WhatWg\Url
seguem rigorosamente os padrões de URL RFC 3986 e WHATWG, respectivamente.
É altamente recomendável usar essas classes para todo o código recém-escrito
e migrar os usos existentes da função parse_url()
para essas classes, a menos que o comportamento de parse_url() precise
ser preservado por motivos de compatibilidade.
Valor Retornado
Em URLs gravemente malformados, parse_url() pode retornar
false.
Se o parâmetro component for omitido, um
array associativo será retornado. Pelo menos um elemento estará
presente no array. As potenciais chaves dentro deste array são:
-
scheme - ex.:
http
-
host
-
port
-
user
-
pass
-
path
-
query - após o ponto de interrogação
?
-
fragment - após a cerquilha
#
Se o parâmetro component for especificado,
parse_url() retornará uma string (ou um
int, no caso de PHP_URL_PORT)
em vez de um array. Se o componente solicitado não existir
no URL fornecido, null será retornado.
A partir do PHP 8.0.0, parse_url() diferencia consultas e fragmentos
ausentes de vazios:
Anteriormente, todos os casos resultavam em consulta e fragmento null.
Observe que os caracteres de controle (compare com ctype_cntrl()) nos
componentes são substituídos por sublinhados (_).
Exemplos
Exemplo #1 Um exemplo de parse_url()
<?php
$url = 'http://username:password@hostname:9090/path?arg=value#anchor';
var_dump(parse_url($url));
var_dump(parse_url($url, PHP_URL_SCHEME));
var_dump(parse_url($url, PHP_URL_USER));
var_dump(parse_url($url, PHP_URL_PASS));
var_dump(parse_url($url, PHP_URL_HOST));
var_dump(parse_url($url, PHP_URL_PORT));
var_dump(parse_url($url, PHP_URL_PATH));
var_dump(parse_url($url, PHP_URL_QUERY));
var_dump(parse_url($url, PHP_URL_FRAGMENT));
?>
O exemplo acima produzirá:
array(8) {
["scheme"]=>
string(4) "http"
["host"]=>
string(8) "hostname"
["port"]=>
int(9090)
["user"]=>
string(8) "username"
["pass"]=>
string(8) "password"
["path"]=>
string(5) "/path"
["query"]=>
string(9) "arg=value"
["fragment"]=>
string(6) "anchor"
}
string(4) "http"
string(8) "username"
string(8) "password"
string(8) "hostname"
int(9090)
string(5) "/path"
string(9) "arg=value"
string(6) "anchor"
Exemplo #2 Um exemplo de parse_url() com esquema ausente
<?php
$url = '//www.example.com/path?googleguy=googley';
// Antes do PHP 5.4.7, o "path" seria "//www.example.com/path"
var_dump(parse_url($url));
?>
O exemplo acima produzirá:
array(3) {
["host"]=>
string(15) "www.example.com"
["path"]=>
string(5) "/path"
["query"]=>
string(17) "googleguy=googley"
}
Notas
Nota:
Esta função destina-se especificamente à análise de URLs e
não de URIs. No entanto, para cumprir os requisitos de compatibilidade com versões
anteriores do PHP, ele abre uma exceção para o esquema file:// onde barras
triplas (file:///...) são permitidas. Para qualquer outro esquema isto é inválido.
