league/uri-parser

userland URI parser RFC 3986 compliant

1.4.1 2018-11-22 07:55 UTC

README

Build Status Latest Version

This package contains a userland PHP URI string parser and builder compliant with:

<?php

use League\Uri\UriString;

var_export(UriString::parse('http://www.example.com/'));
//returns the following array
//array(
//  'scheme' => 'http',
//  'user' => null,
//  'pass' => null,
//  'host' => 'www.example.com',
//  'port' => null,
//  'path' => '/',
//  'query' => null,
//  'fragment' => null,
//);

System Requirements

You need PHP >= 7.1.3 but the latest stable version of PHP is recommended.

While the library no longer requires the ext/intl extension, it is strongly recommended to install this extension if you are dealing with URIs containing non-ASCII host. Without the extension, the parser will throw a InvalidURI exception when trying to parse such URI.

Installation

$ composer require league/uri-parser

Documentation

URI string parsing

<?php

public static function League\Uri\UriString::parse($uri): array

The UriString::parse static method is a drop-in replacement to PHP's parse_url function, with the following differences:

The parser is RFC3986/RFC3987 compliant

<?php

use League\Uri\UriString;

var_export(UriString::parse('http://foo.com?@bar.com/'));
//returns the following array
//array(
//  'scheme' => 'http',
//  'user' => null,
//  'pass' => null,
//  'host' => 'foo.com',
//  'port' => null,
//  'path' => '',
//  'query' => '@bar.com/',
//  'fragment' => null,
//);

var_export(parse_url('http://foo.com?@bar.com/'));
//returns the following array
//array(
//  'scheme' => 'http',
//  'host' => 'bar.com',
//  'user' => 'foo.com?',
//  'path' => '/',
//);
// Depending on the PHP version

The parser returns all URI components.

<?php

use League\Uri\UriString;

var_export(UriString::parse('http://www.example.com/'));
//returns the following array
//array(
//  'scheme' => 'http',
//  'user' => null,
//  'pass' => null,
//  'host' => 'www.example.com',
//  'port' => null,
//  'path' => '/',
//  'query' => null,
//  'fragment' => null,
//);

var_export(parse_url('http://www.example.com/'));
//returns the following array
//array(
//  'scheme' => 'http',
//  'host' => 'www.example.com',
//  'path' => '/',
//);

The parser needs no extra parameters

<?php

use League\Uri\UriString;

$uri = 'http://www.example.com/';

UriString::parse($uri)['query']; //returns null
parse_url($uri, PHP_URL_QUERY); //returns null

The parser treats empty and undefined components differently

A distinction is made between an unspecified component, which will be set to null and an empty component which will be equal to the empty string.

<?php

use League\Uri\UriString;

$uri = 'http://www.example.com?';

UriString::parse($uri)['query'];  //returns ''
parse_url($uri, PHP_URL_QUERY); //returns null

The returned path component is always defined

Since a URI is made of at least a path component, this component is never equal to null

<?php

use League\Uri\UriString;

$uri = 'http://www.example.com?';
UriString::parse($uri)['path'];  //returns ''
parse_url($uri, PHP_URL_PATH); //returns null

The parser throws exception instead of returning false.

<?php

use League\Uri\UriString;

$uri = '//example.com:toto';
UriString::parse($uri);
//throw a League\Uri\Exception\InvalidURI

parse_url($uri); //returns false

The parser is not a validator

Just like parse_url, UriString::parse only parses and extracts components from the URI string.

You still need to validate them against its scheme specific rules.

<?php

use League\Uri\UriString;

$uri = 'http:www.example.com';
var_export(UriString::parse($uri));
//returns the following array
//array(
//  'scheme' => 'http',
//  'user' => null,
//  'pass' => null,
//  'host' => null,
//  'port' => null,
//  'path' => 'www.example.com',
//  'query' => null,
//  'fragment' => null,
//);

URI string building

<?php

public static function League\Uri\UriString::build(array $components): string

You can rebuild a URI from its hash representation returned by the UriString::parse method or PHP's parse_url function using the UriString::build public static method.

If you supply your own hash you are responsible for providing valid encoded components without their URI delimiters.

<?php

use League\Uri\UriString;

$base_uri = 'http://hello:world@foo.com?@bar.com/';
$components = UriString::parse($base_uri);
//returns the following array
//array(
//  'scheme' => 'http',
//  'user' => 'hello',
//  'pass' => 'world',
//  'host' => 'foo.com',
//  'port' => null,
//  'path' => '',
//  'query' => '@bar.com/',
//  'fragment' => null,
//);

$uri = UriString::build($components);

echo $uri; //displays http://hello@foo.com?@bar.com/

Testing

The library has a :

  • a PHPUnit test suite
  • a coding style compliance test suite using PHP CS Fixer.
  • a code analysis compliance test suite using PHPStan.

To run the tests, run the following command from the project folder.

$ composer test

Contributing

Contributions are welcome and will be fully credited. Please see CONTRIBUTING and CONDUCT for details.

Security

If you discover any security related issues, please email nyamsprod@gmail.com instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.