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

Host modifiers

Here’s the documentation for the included URI modifiers which are modifying the URI host component.

Transcoding the host to ascii

Transcodes the host into its ascii representation according to RFC3986:

<?php

use League\Uri\Schemes\Http;
use League\Uri\Modifiers\HostToAscii;

$uri = Http::createFromString("http://스타벅스코리아.com/to/the/sky/");
$modifier = new HostToAscii();
$newUri = $modifier->__invoke($uri);
echo $newUri; //display "http://xn--oy2b35ckwhba574atvuzkc.com/to/the/sky/"

Transcoding the host to its IDN form

Transcodes the host into its idn representation according to RFC3986:

<?php

use League\Uri\Schemes\Http;
use League\Uri\Modifiers\HostToUnicode;

$uriString = "http://xn--oy2b35ckwhba574atvuzkc.com/to/the/./sky/";
$uri = Http::createFromString($uriString);
$modifier = new HostToUnicode();
$newUri = $modifier->__invoke($uri);
echo $newUri; //display "http://스타벅스코리아.com/to/the/sky/"

Removing Zone Identifier

Removes the host zone identifier if present

<?php

use League\Uri\Schemes\Http;
use League\Uri\Modifiers\RemoveZoneIdentifier;

$uriString = 'http://[fe80::1234%25eth0-1]/path/to/the/sky.php';
$uri = Http::createFromString($uriString);
$modifier = new RemoveZoneIdentifier();
$newUri = $modifier->__invoke($uri);
echo $newUri; //display 'http://[fe80::1234]/path/to/the/sky.php'

Appending labels

Description

<?php

public AppendLabel::__construct(string $label)

Appends a label or a host to the current URI host.

Parameters

$label must be a string

Examples

<?php

use League\Uri\Schemes\Http;
use League\Uri\Modifiers\AppendLabel;

$uri = Http::createFromString("http://www.example.com/path/to/the/sky/");
$modifier = new AppendLabel("fr");
$newUri = $modifier->__invoke($uri);
echo $newUri; //display "http://www.example.com.fr/path/to/the/sky/"

Prepending labels

Description

<?php

public PrependLabel::__construct(string $label)

Prepends a label or a host to the current URI path.

Parameters

$label must be a string

Examples

<?php

use League\Uri\Schemes\Http;
use League\Uri\Modifiers\PrependLabel;

$uri = Http::createFromString("http://www.example.com/path/to/the/sky/");
$modifier = new PrependLabel("shop");
$newUri = $modifier->__invoke($uri);
echo $newUri; //display "http://shop.www.example.com/path/to/the/sky/and/above"

Replacing labels

Description

<?php

public ReplaceLabel::__construct(int $offset, string $label)

Replaces a label from the current URI host with a new label or a host.

Parameters

The host is considered as a hierarchical component, labels are indexed from right to left according to host RFC

Examples

<?php

use League\Uri\Schemes\Http;
use League\Uri\Modifiers\ReplaceLabel;

$uri = Http::createFromString("http://www.example.com/path/to/the/sky/");
$modifier = new ReplaceLabel(2, "admin.shop");
$newUri = $modifier->__invoke($uri);
echo $newUri; //display "http://admin.shop.example.com/path/to/the/sky"

Updating the modifier parameters

The withLabel and withOffset methods are deprecated since version 4.1 and will be removed in the next major release.

With the following URI modifiers:

You can update the label string using the withLabel method. This method expects a valid label/host and will return a new instance with the updated info.

<?php

use League\Uri\Schemes\Http;
use League\Uri\Modifiers\ReplaceLabel;

$uri = Http::createFromString("http://www.example.com/path/to/the/sky/");
$modifier = new ReplaceLabel(2, "admin.shop");
$newUri = $modifier->__invoke($uri);
echo $newUri; //display "http://admin.shop.example.com/path/to/the/sky/"
$altModifier = $modifier->withLabel('admin');
$altUri = $altModifier->__invoke($uri);
echo $altUri; //display "http://admin.example.com/path/to/the/sky/"

In case of the ReplaceLabel modifier, the offset can also be modified.

<?php

use League\Uri\Schemes\Http;
use League\Uri\Modifiers\ReplaceLabel;

$uri = Http::createFromString("http://www.example.com/path/to/the/sky/");
$modifier = new ReplaceLabel(2, "admin.shop");
$newUri = $modifier->__invoke($uri);
echo $newUri; //display "http://admin.shop.example.com/path/to/the/sky/"
$altModifier = $modifier->withLabel('thephpleague')->withOffset(1);
$altUri = $altModifier->__invoke($uri);
echo $altUri; //display "http://www.thephpleague.com/path/to/the/sky/"

Removing selected labels

Description

<?php

public RemoveLabels::__construct(array $keys = [])

Removes selected labels from the current URI host. Labels are indicated using an array containing the labels offsets.

The host is considered as a hierarchical component, labels are indexed from right to left according to host RFC

Examples

<?php

use League\Uri\Schemes\Http;
use League\Uri\Modifiers\RemoveLabels;

$uri = Http::createFromString("http://www.example.com/path/to/the/sky/");
$modifier = new RemoveLabels([2]);
$newUri = $modifier->__invoke($uri);
echo $newUri; //display "http://example.com/path/the/sky/"

The withKeys method is deprecated since version 4.1 and will be removed in the next major release

You can update the offsets chosen by using the withKeys method

<?php

use League\Uri\Schemes\Http;
use League\Uri\Modifiers\RemoveLabels;

$uri = Http::createFromString("http://www.example.com/path/to/the/sky/");
$modifier = new RemoveLabels([2]);
$newUri = $modifier->__invoke($uri);
echo $newUri; //display "http://example.com/path/the/sky/"
$altModifier = $modifier->withKeys([0,2]);
$altUri = $altModifier->__invoke($uri);
echo $altUri; //display "http://example/path/to/the/sky/"

Filtering selected labels

Description

<?php

public FilterLabels::__construct(callable $callable, int $flag = 0)

Filter the labels from the current URI host to keep.

Parameters

For Backward compatibility with PHP5.5 which lacks these flags constant you can use the library constants instead:

League\Uri\Interfaces\Collection constantsPHP's 5.6+ constants
Collection::FILTER_USE_KEYARRAY_FILTER_USE_KEY
Collection::FILTER_USE_BOTHARRAY_FILTER_USE_BOTH
Collection::FILTER_USE_VALUE0
<?php

use League\Uri\Schemes\Http;
use League\Uri\Modifiers\FilterLabels;
use League\Uri\Interfaces\Collection;

$uri = Http::createFromString("http://www.example.com/path/to/the/sky/");
$modifier = new FilterLabels(function ($value) {
    return $value > 0 && $value < 2;
}, Collection::FILTER_USE_KEY);
$newUri = $modifier->__invoke($uri);
echo $newUri; //display "http://example/path/to/the/sky/"

Methods

The withCallable and withFlag methods are deprecated since version 4.1 and will be removed in the next major release

You can update the URI modifier using:

<?php

use League\Uri\Schemes\Http;
use League\Uri\Modifiers\FilterLabels;
use League\Uri\Interfaces\Collection;

$uri = Http::createFromString("http://www.example.com/path/to/the/sky/");
$modifier = new FilterLabels(function ($value) {
    return $value > 0 && $value < 2;
}, Collection::FILTER_USE_KEY);
$newUri = $modifier->__invoke($uri);
echo $newUri; //display "http://example/path/to/the/sky/"

$altModifier = $modifier->withCallable(function ($value) {
    return false !== strpos($value, 'm');
})->withFlag(Collection::FILTER_USE_VALUE);
$altUri = $altModifier->__invoke($uri);
echo $altUri; //display "http://example.com/path/to/the/sky/"