The League of Extraordinary Packages

Our Packages:

Presented by The League of Extraordinary Packages

Getting Started

Uri parser

Uri schemes

Uri manipulations

Uri components

Upgrading Guide

URI Objects API

The URI objects are mainly used to validate and normalized URI against RFC3986 and each scheme specific validation rules.

Creating new URI objects

URI instantiation

To instantiate a new URI object you can use two named constructors:

public static Uri::createFromString(string $uri = ''): Uri
public static Uri::createFromComponents(array $components): Uri

The default constructor is protected and can not be accessed to instantiate a new object.

If you supply your own hash to createFromComponents, you are responsible for providing well parsed components without their URI delimiters.

URI validation

A League\Uri\Schemes\UriException exception is triggered if an invalid URI is given.


use League\Uri\Schemes\Data;

$uri = Data::createFromComponents(
// throws a League\Uri\Schemes\UriException
// because the http scheme is not supported

Because createFromString internally use League\Uri\Parser if the supplied URI string is invalid a League\Uri\Exception can be thrown on instantiation.


use League\Uri\Schemes\Http;

$uri = Http::createFromString(':');
// throws a League\Uri\Exception
// because the URI string is invalid

Because the League\Uri\Schemes\UriException exception extends League\Uri\Exception you can catch any exception triggered by the package using the following code.

League\Uri\Exception extends PHP's SPL InvalidArgumentException.


use League\Uri\Exception;
use League\Uri\Schemes\Http;

try {
	$uri = Http::createFromString(':');
} catch (Exception $e) {
	//$e is either League\Uri\Exception
	//or League\Uri\Schemes\UriException

Accessing URI properties

All URI objects expose the same methods. You can access the URI string, its individual parts and components using their respective getter methods.


public Uri::__toString(): string
public Uri::getScheme(void): string
public Uri::getUserInfo(void): string
public Uri::getHost(void): string
public Uri::getPort(void): int|null
public Uri::getAuthority(void): string
public Uri::getPath(void): string
public Uri::getQuery(void): string
public Uri::getFragment(void): string

Which will lead to the following result for a simple HTTP URI:


use League\Uri\Schemes\Http;

$uri = Http::createFromString("");
echo $uri;                 //displays ""
echo $uri->getScheme();    //displays "http"
echo $uri->getUserInfo();  //displays "foo:bar"
echo $uri->getHost();      //displays ""
echo $uri->getPort();      //displays 81 as an integer
echo $uri->getAuthority(); //displays ""
echo $uri->getPath();      //displays "/how/are/you"
echo $uri->getQuery();     //displays "foo=baz"
echo $uri->getFragment();  //displays "title"

Modifying URI properties

To replace one of the URI part you can use the modifying methods exposed by all URI object. If the modifications do not alter the current object, it is returned as is, otherwise, a new modified object is returned.

Any modification method can trigger a League\Uri\Schemes\UriException exception if the resulting URI is not valid. Just like with the instantiation methods, validition is scheme dependant.


public Uri::withScheme(string $scheme): self
public Uri::withUserInfo(string $user [, string $password = null]): self
public Uri::withHost(string $host): self
public Uri::withPort(int|null $port): self
public Uri::withPath(string $path): self
public Uri::withQuery(string $query): self
public Uri::withFragment(string $fragment): self

Since All URI object are immutable you can chain each modifying methods to simplify URI creation and/or modification.


use League\Uri\Schemes\Ws;

$uri = Ws::createFromString("ws://")
    ->withUserInfo("foo", "bar")

echo $uri; //displays wss://

URI normalization

Out of the box the package normalizes any given URI according to the non destructive rules of RFC3986.

These non destructives rules are:


use League\Uri\Schemes\Http as HttpUri;

$uri = HttpUri::createFromString("hTTp:// ld?who=f 3#title");
echo $uri; //displays

$uri = HttpUri::createFromComponent(parse_url("hTTp://www.bébé.be?#"));
echo $uri; //displays