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

The Host component

The library provides a League\Uri\Components\Host class to ease complex host manipulation.

Host creation

Using the default constructor

A new League\Uri\Components\Host object can be instantiated using the default constructor.

<?php

use League\Uri\Components\Host;

$host = new Host('shop.example.com');
echo $host; //display 'shop.example.com'

$fqdn = new Host('shop.example.com.');
echo $fqdn; //display 'shop.example.com.'

$ipv4 = new Host('127.0.0.1');
echo $ipv4; //display '127.0.0.1'

$ipv6 = new Host('::1');
echo $ipv6; //display '[::1]'

$ipv6_alt = new Host('[::1]');
echo $ipv6_alt; //display '[::1]'

If the submitted value is not a valid host an InvalidArgumentException will be thrown.

Using a League Uri object

You can also access a Host object from a Uri object:

<?php

use League\Uri\Schemes\Http as HttpUri;

$uri  = HttpUri::createFromString('http://uri.thephpleague.com/');
$host = $uri->host; // $host is a League\Uri\Components\Host object;

Using a named constructor

Since version 4.2 createFromLabels replaces createFromArray. createFromArray is deprecated and will be removed in the next major release

A host is a collection of labels delimited by the host separator .. So it is possible to create a Host object using a collection of labels with the Host::createFromLabels method.

The method expects at most 2 arguments:

By default this optional argument equals to Host::IS_RELATIVE.

Since an IP is not a hostname, the class will throw an InvalidArgumentException if you try to create an fully qualified domain name with a valid IP address.

<?php

use League\Uri\Components\Host;

$host = Host::createFromLabels(['com', 'example', 'shop']);
echo $host; //display 'shop.example.com'

$fqdn = Host::createFromLabels(['com', 'example', 'shop'], Host::IS_ABSOLUTE);
echo $fqdn; //display 'shop.example.com.'

$ip_host = Host::createFromLabels(['0.1', '127.0']);
echo $ip_host; //display '127.0.0.1'

Host::createFromLabels(['0.1', '127.0'], Host::IS_ABSOLUTE);
//throws InvalidArgumentException

Normalization

Whenever you create a new host your submitted data is normalized using non desctructive operations:

<?php

use League\Uri\Components\Host;

$host = Host::createFromLabels(['com', 'ExAmPle', 'shop']);
echo $host; //display 'shop.example.com'

$ipv6 = new Host('::1');
echo $ipv6; //display '[::1]'

Host types

IP address or hostname

There are two type of host:

To determine what type of host you are dealing with the Host class provides the isIp method:

<?php

use League\Uri\Components\Host;
use League\Uri\Schemes\Http as HttpUri;

$host = new Host('::1');
$host->isIp();   //return true

$alt_host = new Host('example.com');
$host->isIp(); //return false;

HttpUri::createFromServer($_SERVER)->host->isIp(); //return a boolean

IPv4 or IPv6

Knowing that you are dealing with an IP is good, knowing that its an IPv4 or an IPv6 is better.

<?php

use League\Uri\Components\Host;

$ipv6 = new Host('::1');
$ipv6->isIp();   //return true
$ipv6->isIpv4(); //return false
$ipv6->isIpv6(); //return true

$ipv4 = new Host('127.0.0.1');
$ipv4->isIp();   //return true
$ipv4->isIpv4(); //return true
$ipv4->isIpv6(); //return false

The object can also detect if the IPv6 has a zone identifier or not. This can be handy if you want to know if you need to remove it or not for security reason.

<?php

use League\Uri\Components\Host;

$ipv6 = new Host('Fe80::4432:34d6:e6e6:b122%eth0-1');
$ipv6->hasZoneIdentifier(); //return true

$ipv4 = new Host('127.0.0.1');
$ipv4->hasZoneIdentifier(); //return false

Relative or fully qualified domain name

If you don’t have a IP then you are dealing with a host name. A host name is a domain name subset according to RFC1123. As such a host name can not, for example, contain an _.

A host name is considered absolute or as being a fully qualified domain name (FQDN) if its string representation ends with a ., otherwise it is known as being a relative or a partially qualified domain name (PQDN).

<?php

use League\Uri\Components\Host;

$host = new Host('example.com');
$host->isIp();       //return false
$host->isAbsolute(); //return false

$fqdn = new Host('example.com.');
$fqdn->isIp();       //return false
$fqdn->isAbsolute(); //return true

$ip = new Host('::1');
$ip->isIp();       //return true
$ip->isAbsolute(); //return false

Host representations

String representation

Basic host representations is done using the following methods:

<?php

use League\Uri\Components\Host;

$host = new Host('example.com');
$host->__toString();      //return 'example.com'
$host->getUriComponent(); //return 'example.com'
$host->getLiteral();      //return 'example.com'
$host->getContent();      //return 'example.com'

$ipv4 = new Host('127.0.0.1');
$ipv4->__toString();      //return '127.0.0.1'
$ipv4->getUriComponent(); //return '127.0.0.1'
$ipv4->getLiteral();      //return '127.0.0.1'
$ipv4->getContent();      //return '127.0.0.1'

$ipv6 = new Host('::1');
$ipv6->__toString();      //return '[::1]'
$ipv6->getUriComponent(); //return '[::1]'
$ipv6->getLiteral();      //return '::1'
$ipv6->getContent();      //return '127.0.0.1'

The Host::getLiteral is deprecated and will be remove in the next major release. Please use instead the new method Host::getContent.

IDN support

The Host class supports the IDN mechanism.

At any given time the object can tell you if the submitted hostname is a IDN or not using the Host::isIdn() method.

<?php

use League\Uri\Components\Host;

$idn_host = new Host('스타벅스코리아.com');       //you set a IDN hostname
echo $idn_host->isIdn(); //return true

$host = new Host('xn--mgbh0fb.xn--kgbechtv');  //you set a ascii hostname
echo $host->isIdn();     //return false

$host = new Host('192.168.2.56');              //you set a IP host
echo $host->isIdn();     //return false

Array representation

Since version 4.2 toArray replaces getLabels. toArray is deprecated and will be removed in the next major release

A host can be splitted into its different labels. The class provides an array representation of a the host labels using the Host::getLabels method. If the host is an IP, the array contains only one entry, the full IP.

The class uses a hierarchical representation of the Hostname. This mean that the host top-level domain is the array first item.

<?php

use League\Uri\Components\Host;

$host = new Host('secure.example.com');
$arr = $host->getLabels(); //return  ['com', 'example', 'secure'];

$fqdn = new Host('secure.example.com.');
$arr = $fqdn->getLabels(); //return ['com', 'example', 'secure'];

$host = new Host('::1');
$arr = $host->getLabels(); //return ['::1'];

Once in array representation you can not distinguish a partially from a fully qualified domain name.

Accessing host contents

Countable and IteratorAggregate

The class provides several methods to works with its labels. The class implements PHP’s Countable and IteratorAggregate interfaces. This means that you can count the number of labels and use the foreach construct to iterate over them.

<?php

use League\Uri\Components\Host;

$host = new Host('secure.example.com');
count($host); //return 3
foreach ($host as $offset => $label) {
    echo $labels; //will display "com", then "example" and last "secure"
}

Label keys

If you are interested in getting all the label keys you can do so using the Host::keys method like shown below:

<?php

use League\Uri\Components\Host;

$host = new Host('uk.example.co.uk');
$host->keys();        //return [0, 1, 2, 3];
$host->keys('uk');    //return [0, 3];
$host->keys('gweta'); //return [];

The methods returns all the label keys, but if you supply an argument, only the keys whose label value equals the argument are returned.

To know If a key exists before using it you can use the Host::hasKey method which returns true or false depending on the presence or absence of the submitted key in the current object.

<?php

use League\Uri\Components\Host;

$host = new Host('uk.example.co.uk');
$host->hasKey(2);  //return true
$host->hasKey(23); //return false

Label content

If you are only interested in a given label you can access it directly using the Host::getLabel method as show below:

<?php

use League\Uri\Components\Host;

$host = new Host('example.co.uk');
$host->getLabel(0);         //return 'uk'
$host->getLabel(23);        //return null
$host->getLabel(23, 'now'); //return 'now'

If the offset does not exists it will return the value specified by the optional second argument or null.

Host public informations

Using data from the public suffix list and the PHP Domain Parser library every Host object can:

<?php

use League\Uri\Components\Host;

$host = new Host('www.example.co.uk');
echo $host->getPublicSuffix();        //display 'co.uk'
echo $host->getRegisterableDomain();  //display 'example.co.uk'
echo $host->getSubdomain();           //display 'www'
$host->isPublicSuffixValid();         //return a boolean 'true' in this example

a bug fix is introduced in version 4.2. The methods always return a string to be compatible with the Host interface contract. Before null was returned.

If the data is not found the methods listed above will all return an empty string except for the Host::isPublicSuffixValid method which will return false.

<?php

use League\Uri\Components\Host;

$host = new Host('192.158.26.30');
echo $host->getPublicSuffix();        //return ''
echo $host->getRegisterableDomain();  //return ''
echo $host->getSubdomain();           //return ''
$host->isPublicSuffixValid();         //return false

Modifying the host

If the modifications do not change the current object, it is returned as is, otherwise, a new modified object is returned.

When a modification fails an InvalidArgumentException exception is thrown.

Transcode the host

You can transcode the Host so that its string representation match the IDN support you need.

<?php

use League\Uri\Components\Host;

$idn_host = new Host('스타벅스코리아.com'); //you set a IDN hostname
echo $idn_host->__toString();            //display '스타벅스코리아.com'
echo $idn_host->toAscii()->__toString(); //display 'xn--oy2b35ckwhba574atvuzkc.com'
echo $idn_host->toUnicode->__toString(); //display '스타벅스코리아.com'

$host = new Host('xn--mgbh0fb.xn--kgbechtv');  //you set a ascii hostname
echo $host->__toString();              //display 'xn--mgbh0fb.xn--kgbechtv'
echo $host->toAscii()->__toString();   //display 'xn--mgbh0fb.xn--kgbechtv'
echo $host->toUnicode()->__toString(); //display 'مثال.إختبار'

These methods are used by the URI modifiers HotToAscii and HotToUnicode

Append labels

To append labels to the current host you need to use the Host::append method. This method accepts a single argument which represents the data to be appended. This data can be:

<?php

use League\Uri\Components\Host;

$host    = new Host();
$newHost = $host->append('toto')->append(new Host('example.com'));
$newHost->__toString(); //return toto.example.com

This method is used by the URI modifier appendLabels

Prepend labels

To prepend labels to the current host you need to use the Host::prepend method. This method accept a single argument which represents the data to be prepended. This data can be:

<?php

use League\Uri\Components\Host;

$host    = new Host();
$newHost = $host->prepend('example.com')->prepend(new Host('toto'));
$newHost->__toString(); //return toto.example.com

This method is used by the URI modifier prependLabels

Replace label

To replace a label you must use the Host::replace method with two arguments:

<?php

use League\Uri\Components\Host;

$host    = new Host('foo.example.com');
$newHost = $host->replace(2, 'bar.baz');
$newHost->__toString(); //return bar.baz.example.com

if the specified offset does not exist, no modification is performed and the current object is returned.

This method is used by the URI modifier replaceLabel

Remove labels

To remove labels from the current object you can use the Host::without method. This method expects a single argument and will returns a new Host object without the selected labels. The argument is an array containing a list of offsets to remove.

<?php

use League\Uri\Components\Host;

$host    = new Host('toto.example.com');
$newHost = $host->without([1]);
$newHost->__toString(); //return toto.com

if the specified offsets do not exist, no modification is performed and the current object is returned.

This method is used by the URI modifier RemoveSegments

Remove zone identifier

According to RFC6874:

You must remove any ZoneID attached to an outgoing URI, as it has only local significance at the sending host.

To fullfill this requirement, the Host::withoutZoneIdentifier method is provided. The method takes not parameter and return a new host instance without its zone identifier. If the host has not zone identifier, the current instance is returned unchanged.

<?php

use League\Uri\Components\Host;

$host    = new Host('[fe80::1%25eth0-1]');
$newHost = $host->withoutZoneIdentifier();
echo $newHost; //displays '[fe80::1]';

This method is used by the URI modifier RemoveZoneIdentifier

Filter labels

You can filter the Host object using the Host::filter method. Filtering is done using the same arguments as PHP’s array_filter.

You can filter the host according to its labels values:

<?php

use League\Uri\Components\Host;

$host    = new Host('www.11.be');
$newHost = $host->filter(function ($value) {
	return !is_numeric($value);
}, Host::FILTER_USE_VALUE);
echo $newHost; //displays 'www.be'

You can filter the host according to its labels key.

<?php

use League\Uri\Components\Host;

$host    = new Host('www.11.be');
$newHost = $host->filter(function ($value) {
	return $value != 2;
}, Host::FILTER_USE_KEY);
echo $newHost; //displays '11.be'

You can filter the host according to its label value and key.

<?php

use League\Uri\Components\Host;

$host    = new Path('media.bbc.co.uk');
$newHost = $query->filter(function ($value, $key) {
    return 1 != $key && strpos($value, 'e') === false;
}, Path::FILTER_USE_BOTH);
echo $newHost; //displays 'bbc.uk'

By specifying the second argument flag you can change how filtering is done:

By default, if no flag is specified the method will filter the host using the Host::FILTER_USE_VALUE flag.

If you are in PHP 5.6+ you can substitute these constants with PHP's array_filter flags constants ARRAY_FILTER_USE_KEY and ARRAY_FILTER_USE_BOTH

This method is used by the URI modifier FilterLabels