The League of Extraordinary Packages

Our Packages:

Presented by The League of Extraordinary Packages

Getting Started

Uri

Uri Schemes

Uri manipulation

Uri Parts API

Services

Upgrading Guide

This is the documentation for the unsupported version 4.0. Please consider upgrading your code to the latest stable version

Terminology

The library models URIs and URIs components as immutable value objects.

URI, URL and URN

Often you will encounter in the public spaces the following terms:

But according to RFC3986

Future specifications and related documentation should use the general term “URI” rather than the more restrictive terms “URL” and “URN”.

This is the reason why you will only encounter the term URI throughout the documentation to highlight the fact that the package is not limited to HTTP(S) URI or any other scheme specific URI.

Value Objects

The term “Uniform Resource Locator” (URL) refers to the subset of URIs that, in addition to identifying a resource, provide a means of locating the resource by describing its primary access mechanism. RFC3986

This means that an URI is like a street address, if you omit or change even a single character in it, you won’t be able to clearly identify what your are looking for. This means that the equality between instances of URI objects is not based on identity but rather on content.

<?php

use League\Uri\Schemes\Http as HttpUri;

$uri1 = HttpUri::createFromString("http://example.com:81/toto");
$uri2 = HttpUri::createFromString("http://example.com:81/toto");
//will be considered equal because
$uri1->__toString() === $uri2->__toString(); //return true;
//even if their identities are different
$uri === $uri2; //return false;

Immutability

To ensure the integrity of the value, when a component is altered instead of modifying its current value, we return a new component with the changed value. This practice is called immutability.

<?php

use League\Uri\Schemes\Http as HttpUri;

$uri1 = HttpUri::createFromString("http://example.com:81/toto");
$uri2 = $uri1->withPort(82);
echo $uri1; //still displays "http://example.com:81/toto"
echo $uri2; //displays "http://example.com:82/toto"

Using these concepts, the package enforces stronger and efficient manipulation of URIs and URI components.