parse_url

(PHP 4, PHP 5, PHP 7, PHP 8)

parse_url — Analisa uma URL e retorna seus componentes

Descrição

parse_url(string $url, int $component = -1): int|string|array|null|false

Esta função analisa uma URL e retorna um array associativo contendo cada um dos vários componentes da URL presentes. Os valores dos elementos do array não são decodificados como URL.

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.

Caution

Esta função pode não fornecer resultados corretos para URLs relativos ou inválidos, e os resultados podem nem mesmo corresponder ao comportamento comum de clientes HTTP. Se URLs de entradas não confiáveis ​​precisarem ser analisados, será necessária validação extra, por exemplo, usando filter_var() com o filtro FILTER_VALIDATE_URL.

Parâmetros

url

A URL a ser analisada.

component

Deve ser especificada uma das constantes PHP_URL_SCHEME, PHP_URL_HOST, PHP_URL_PORT, PHP_URL_USER, PHP_URL_PASS, PHP_URL_PATH, PHP_URL_QUERY ou PHP_URL_FRAGMENT para recuperar apenas um componente específico da URL como uma string (exceto quando PHP_URL_PORT for informada, que no caso o valor de retorno será um int).

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: 

http://example.com/foo → consulta = null, fragmento = null
http://example.com/foo? → consulta = "",   fragmento = null
http://example.com/foo# → consulta = null, fragmento = ""
http://example.com/foo?# → consulta = "",   fragmento = ""

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 (_).

Registro de Alterações

Versão Descrição
8.0.0 parse_url() agora diferencia consultas e fragmentos vazios de ausantes.

Exemplos

Example #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"

Example #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

Note:

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.

Veja Também