The League of Extraordinary Packages

Our Packages:

Presented by The League of Extraordinary Packages

Getting Started

Uri functions

Uri parser

Uri schemes

Uri manipulations

Uri components

Uri Domain Parser

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.

<?php
class Host implements ComponentInterface, Countable, IteratorAggregate
{
	const IS_ABSOLUTE = 1;
	const IS_RELATIVE = 0;
	public static function createFromIp(string $ip): self
	public static function createFromLabels(iterable $data, int $type = self::IS_RELATIVE): self
	public function __construct(?string $content = null): void
	public function append(string $host): self
	public function getIp(void): string
	public function getLabel(int $offset, $default = null): mixed
	public function getLabels(void): array
	public function getPublicSuffix(void): string
	public function getRegistrableDomain(void): string
	public function getSubDomain(void): string
	public function hasZoneIdentifier(void): bool
	public function isIp(void): bool
	public function isIpv4(void): bool
	public function isIpv6(void): bool
	public function isPublicSuffixValid(void): bool
	public function isAbsolute(void): bool
	public function keys([string $label]): array
	public function prepend(string $host): self
	public function replaceLabel(int $offset, string $host): self
	public function withoutLabels(array $offsets): self
	public function withoutRootLabel(void): self
	public function withoutZoneIdentifier(void): self
	public function withRegistrableDomain(string $host): self
	public function withRootLabel(void): self
	public function withSubDomain(string $host): self
}

Creating a new object using the default constructor

<?php
public Host::__construct(?string $content = null): void

submitted string is normalized to be RFC3986 compliant.

If the submitted value is not valid a League\Uri\Components\Exception exception is thrown.

The League\Uri\Components\Exception extends PHP’s SPL InvalidArgumentException.

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 domain name

Host::getRegisterableDomain and Host::withRegisterableDomain are deprecated and replaced by Host::getRegistrableDomain and Host::withRegistrableDomain starting with version 1.5.0.

If you don’t have a IP then you are dealing with a registered name. A registered name can be a domain name subset if it follows RFC1123 but it is not a requirement as stated in RFC3986

(…) URI producers should use names that conform to the DNS syntax, even when use of DNS is not immediately apparent, and should limit these names to no more than 255 characters in length.

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

Host public informations

Using data from the public suffix list 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->getRegistrableDomain();  //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->getRegistrableDomain();  //return ''
echo $host->getSubDomain();           //return ''
$host->isPublicSuffixValid();         //return false

Updating the Registrable domain part

You can update the registrable domain part of the host.

<?php

use League\Uri\Components\Host;

$host    = new Host('www.11.be');
$newHost = $host->withRegistrableDomain('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 general registered name

<?php
const Host::IS_RELATIVE = 0;
const Host::IS_ABSOLUTE = 1;
public static Host::createFromLabels(iterable $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 registered 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.