Analyse une URL et retourne ses composants

# parse_url

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

parse_url — Analyse une URL et retourne ses composants

### Description

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

Cette fonction analyse une URL et retourne un tableau associatif contenant tous les éléments qui y sont présents. Les valeurs des éléments du tableau NE sont PAS URL décodées.

Cette fonction n'est pas faite pour valider l'URL fournie, elle ne fait que la découper en parties listées ci-dessous. Les URL partielles et invalides sont également acceptées, la fonction parse_url() fera de son mieux pour les analyser correctement.

Attention

Cette fonction ne suit aucun standard URI ou URL établi. Elle retournera des résultats incorrects ou incohérents pour les URL relatives ou malformées. Même pour des URL valides, le résultat peut différer de celui d'un autre analyseur d'URL, car il existe plusieurs standards différents liés aux URL qui ciblent des cas d'utilisation différents et qui diffèrent dans leurs exigences.

Le traitement d'une URL avec des analyseurs suivant des standards d'URL différents est une source courante de vulnérabilités de sécurité. Par exemple, la validation d'une URL contre une liste de noms d'hôtes autorisés avec l'analyseur A pourrait être inefficace lorsque la récupération réelle de la ressource utilise l'analyseur B qui extrait les noms d'hôtes différemment.

Les classes Uri\Rfc3986\Uri et Uri\WhatWg\Url suivent strictement les standards RFC 3986 et WHATWG URL respectivement. Il est fortement recommandé d'utiliser ces classes pour tout nouveau code et de migrer les utilisations existantes de la fonction parse_url() vers ces classes, à moins que le comportement de parse_url() ne doive être préservé pour des raisons de compatibilité.

### Liste de paramètres

`url`

  L'URL à analyser.

`component`

  Peut être une des constantes parmi `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` pour récupérer uniquement une partie de l'URL en tant que chaîne de caractères (sauf lorsque `PHP_URL_PORT` est fourni ; dans ce cas, la valeur retournée sera un entier).

### Valeurs de retour

Pour les URL vraiment mal formées, parse_url() peut retourner `false`.

Si le paramètre `component` est omis, un array associatif est retourné. Au moins un élément sera présent dans le tableau. Voici les clés potentielles de ce tableau:

- scheme - par exemple `http`
- host
- port
- user
- pass
- path
- query - après le point d'interrogation "`?`"
- fragment - après le croisillon (dièse) "`#`"

Si le paramètre `component` est spécifié, parse_url() retourne une string (ou un entier dans le cas d'utilisation de la constante `PHP_URL_PORT`) au lieu d'un array. Si le composant demandé n'existe pas dans l'URL, `null` sera retourné. À partir de PHP 8.0.0, parse_url() distingue entre les fragments et requêtes absentes et vides :

    http://example.com/foo → query = null, fragment = null
    http://example.com/foo? → query = "",   fragment = null
    http://example.com/foo# → query = null, fragment = ""
    http://example.com/foo?# → query = "",   fragment = ""

Précédemment tous les cas résultaient en la requête et le fragment étant `null`.

À noter que les caractères de contrôle (cf. ctype_cntrl()) dans les composants sont remplacés par un tiret du bas (`_`).

### Historique

Version | Description
--- | ---
8.0.0 | parse_url() distingue désormais entre les fragments et requêtes absentes et vides.

### Exemples

Exemple #1 Exemple avec 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));
    ?>

L'exemple ci-dessus va afficher :

    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"

Exemple #2 Exemple avec la fonction parse_url() sans schéma

    <?php
    $url = '//www.example.com/path?googleguy=googley';

    // Avant PHP 5.4.7, le chemin sera "//www.example.com/path"
    var_dump(parse_url($url));
    ?>

L'exemple ci-dessus va afficher :

    array(3) {
      ["host"]=>
      string(15) "www.example.com"
      ["path"]=>
      string(5) "/path"
      ["query"]=>
      string(17) "googleguy=googley"
    }

### Notes

> Note:

> parse_url() a été créée tout spécialement pour analyser les URL et non les URI. Cependant, pour des raisons de rétrocompatibilité, PHP fait une exception pour le schéma `file://` où les triples slashs (`file:///`...) sont autorisés. Tous les autres schémas sont invalides.

### Voir aussi

- pathinfo() - Retourne des informations sur un chemin système
- parse_str() - Analyse une chaîne de caractères comme une chaîne de requête URL
- http_build_query() - Génère une chaîne de requête en encodage URL
- dirname() - Renvoie le chemin du dossier parent
- basename() - Retourne le nom de la composante finale d'un chemin
- » RFC 3986

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open