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

The Host

The library provides a Host class to ease host creation and manipulation. This URI component object exposes the package common API, but also provide specific methods to work with the URI host component.

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 League\Uri\Components\Exception exception is thrown.

Host represented by an IP

<?php

public static Host::createFromIp(string $ip): self
public Host::isIp(void): bool
public Host::isIpv4(void): bool
public Host::isIpv6(void): bool
public Host::hasZoneIdentifier(void): bool
public Host::getIp(void): string
public Host::withoutZoneIdentifier(void): self

Host::createFromIp

This method allow creating an Host object from an IP. If the submitted IP is invalid a League\Uri\Components\Exception exception is thrown.

<?php

use League\Uri\Components\Host;

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

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

Host::createFromIp('uri.thephpleague.com');
//throws League\Uri\Components\Exception

IPv4 or IPv6

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;

$host = new Host('example.com');
$host->isIp(); //return false;
$ip_host = $host->withContent('127.0.0.1');
$ip_host->isIp(); //return true;

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 = Host::createFromIp('::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

Zone Identifier

Detecting the presence of the Zone Identifier

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

Removing the 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]';

Getting the IP string representation

You can retrieve the IP string representation from the Host object using the getIp method. If the Host is not an IP null will be returned instead.

<?php

use League\Uri\Components\Host;

$host = new Host('[fe80::1%25eth0-1]');
$host->getIp(); //returns 'fe80::1%eth0-1'

$newHost = $host->withContent('uri.thephpleague.com');
$newHost->getIp(); //returns null

Host represented by a registered name

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

<?php
public Host::getPublicSuffix(void): string
public Host::isPublicSuffixValid(void): bool
public Host::getRegisterableDomain(void): string
public Host::getSubDomain(void): string
public Host::withRegisterableDomain(string $host): self
public Host::withSubDomain(string $host): self

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

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

Updating the Registerable domain part

You can update the registerable domain part of the host.

<?php

use League\Uri\Components\Host;

$host    = new Host('www.11.be');
$newHost = $host->withRegisterableDomain('co.uk');
echo $newHost; //displays 'www.11.co.uk'

This method throws an League\Uri\Components\Exception if you submit a FQDN.

Update the Host subdomains

You can update the subdomain part of the host.

<?php

use League\Uri\Components\Host;

$host    = new Host('www.11.be');
$newHost = $host->withSubdomain('shop');
echo $newHost; //displays 'shop.11.be'

This method throws an League\Uri\Components\Exception if you submit a FQDN.

Host as a Hierarchical Collection

<?php
const Host::IS_RELATIVE = 0;
const Host::IS_ABSOLUTE = 1;
public static Host::createFromLabels($data, int $type = self::IS_RELATIVE): self
public Host::isAbsolute(void): bool
public Host::getLabels(void): array
public Host::getLabel(int $offset, $default = null): mixed
public Host::keys([string $label]): array
public Host::count(void): int
public Host::getIterator(void): ArrayIterator
public Host::withRootLabel(void): self
public Host::withoutRootLabel(void): self
public Host::prepend(string $host): self
public Host::append(string $host): self
public Host::replaceLabel(int $offset, string $host): self
public Host::withoutLabels(array $offsets): self

Host::createFromLabels

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 League\Uri\Components\Exception 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 League\Uri\Components\Exception

Partial or fully qualified domain name

A host is considered absolute or as being a fully qualified domain name (FQDN) if it contains a root label, 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

IP type host can not be FQDN

Updating the host status

To update the host state from FDQN to a PQDN and vice-versa you can use 2 methods

These methods which takes not argument add or remove the root empty label from the host as see below:

<?php

use League\Uri\Components\Host;

$host = new Host('www.11.be');
echo $host->withRootLabel() //display 'www.11.be.'
echo $host->withoutRootLabel() //display 'www.11.be'

Trying to update the root label of an IP type host will trigger a League\Uri\Components\Exception

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'

$host = Host::createFromLabels(['be', 'bébé']);
echo $host; //display 'xn--bb-bjab.be'

Accessing the Host labels

Host iterable representation

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 FQDN from a PQDN

The class also 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"
}

The returned label is encoded following RFC3987.

Accessing Host label offset

If you are interested in getting the label offsets you can do so using the Host::keys method.

<?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 method returns all the label keys, but if you supply an argument, only the keys whose label value equals the argument are returned.

The supplied argument is RFC3987 encoded to enable matching the corresponding keys.

Accessing Host label value

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'

Host::getLabel always returns the RFC3987 label representation.

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

`Host::getLabel supports negative offsets

<?php

use League\Uri\Components\Host;

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

Manipulating the host labels

Appending 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 a string or null.

<?php

use League\Uri\Components\Host;

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

Prepending 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 a string or null.

<?php

use League\Uri\Components\Host;

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

Replacing labels

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

<?php

use League\Uri\Components\Host;

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

Just like the Host::getLabel this method supports negative offset.

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

Removing labels

To remove labels from the current object you can use the Host::withoutLabels 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->withoutLabels([1]);
$newHost->__toString(); //return toto.com

Just like the Host::getLabel this method supports negative offset.

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