The League of Extraordinary Packages

Our Packages:

Presented by The League of Extraordinary Packages

Getting Started

The API

The Components

Url is end of life. We strongly encourage you to use League\Uri instead.

Overview

The library handles FTP, HTTP and Websocket protocol URLs through the use of two main classes:

Both classes implement the League\Url\UrlInterface interface.

Think of PHP DateTime and DateTimeImmutable classes which implement the DateTimeInterface interface.

While the library validates the host syntax, it does not validate your host against a valid public suffix list.

Instantiation

Both classes share the same named constructors to ease object instantiation. In the example below I’ll use the League\Url\Url object as an example, which is also applicable for League\Url\UrlImmutable.

<?php

use League\Url\Url;

//Method 1 : from a given URLs
$url = Url::createFromUrl('ftp://host.example.com');

//Method 2: from the current PHP page
//don't forget to provide the $_SERVER array
$url = Url::createFromServer($_SERVER);

$url is a League\Url\Url object.

Accessing URL properties

Once you have instantiated a Url or a UrlImmutable object you can access its properties using the following getter methods:

On URL output, the query string is automatically encoded following RFC 3986.

UrlInterface::__toString()

Returns the full string representation of the URL;

UrlInterface::getUserInfo()

Returns the string representation of the URL user info;

UrlInterface::getAuthority()

Returns the string representation of the URL authority part (ie: user, pass, host, port);

UrlInterface::getBaseUrl()

Returns the string representation of the URL scheme component and authority part;

UrlInterface::getRelativeUrl(UrlInterface $ref_url = null)

the $ref_url argument was added in version 3.2

Returns the string representation of the URL relative to another League\Url\UrlInterface object;

UrlInterface::sameValueAs(UrlInterface $ref_url)

Returns true if two League\Url\UrlInterface object represents the same URL.

UrlInterface::toArray()

added in version 3.3

Returns the URL component as an array like PHP native parse_url but all components are always returned even when missing from the full URL.

<?php

use League\Url\Url;
use League\Url\UrlImmutable;

$url = Url::createFromUrl('http://www.example.com/path/index.php?query=toto+le+heros');
$relative_url = Url::createFromUrl('http://www.example.com/path/another/index.html');
echo $url; // 'http://www.example.com/path/index.php?query=toto%20le%20heros'
echo $url->getBaseUrl(); // http://www.example.com
echo $url->getRelativeUrl(); // /path/index.php?query=toto%20le%20heros
echo $url->getRelativeUrl($relative_url); // ../../index.php?query=toto%20le%20heros

$original_url = Url::createFromUrl("example.com"); //a schemeless url
$new_url = UrlImmutable::createFromUrl("//example.com"); //another schemeless url
$alternate_url = Url::createFromUrl("http://example.com");

$original_url->sameValueAs($new_url); //will return true
$original_url->sameValueAs($alternate_url); //will return false

$url->toArray();
//returns a array with all the component
// array(
//     'scheme' => 'http',
//     'user' => null,
//     'pass' => null,
//     'host' => 'www.example.com',
//     'port' => null,
//     'path' => 'path/index.php',
//     'query' => 'query=toto+le+heros',
//     'fragment' => null,
// );

Manipulating URLs

A URL string is composed of 8 components. In League\Url each component is represented by a specific object you can accessed on League\Url\UrlInterface through their respective setter and getter methods.

Scheme getter and setter

User getter and setter

Pass getter and setter

Host getter and setter

Port getter and setter

Path getter and setter

Query getter and setter

Fragment getter and setter

For all setter methods $data argument can be:

For the host, path and query components, $data can also be an array or a Traversable object;

Manipulation examples

Let’s modify a League\Url\Url object:

<?php

$url = Url::createFromUrl('https://www.example.com');
$url
	->setUser('john')
	->setPass('doe')
	->setPort(443)
	->setScheme('https');
echo $url; // https://john:doe@www.example.com:443/

$port = $url->getPort();
$port->set(80);
echo $port; // output 80;
echo $url; // https://john:doe@www.example.com:80/
To stay immutable, the League\Url\UrlImmutable object:
  • never modified itself but returns a new object instead.
  • returns a new property object instead of its own property object to avoid modification by reference.

The same operation using a League\Url\UrlImmutable object:

<?php

$url = UrlImmutable::createFromUrl('http://www.example.com');
$new_url = $url
	->setUser('john')
	->setPass('doe')
	->setPort(443)
	->setScheme('https');
echo $url; //remains http://www.example.com/
echo $new_url; //output https://john:doe@www.example.com:443/

$port = $new_url->getPort(); //$port is a clone object of the URL port component.
echo $port // output 443;
$port->set(80);
echo $port; // output 80;
echo $new_url->getPort(); //remains 443