Please consider using the the latest stable version for any production code.

The Domain Host

The library provides a Domain class to ease domain host creation and manipulation.

The class validates domain names according to RFC952 and RFC1123

In addition it exposes:

the package common API,
the Host common API,

but also provide specific methods to work with a URI domain host component.

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

If the submitted value is not valid a League\Uri\Exceptions\SyntaxError exception is thrown.

Creating a new object

Using the default constructor

The default constructor is deprecated starting with version 2.3.0. It should be replaced by one of the several new named constructors.

<?php
public Domain::__construct($host)

submitted string is normalized to be RFC3986 compliant.

The $host can not be null or the empty string as they represents an invalid domain name.

Using a string

<?php

use League\Uri\Components\Domain;

$authority = Domain::createFromString('example.com');
$authority->getContent(); //returns 'example.com'

Using a Host object

<?php

use League\Uri\Components\Domain;
use League\Uri\Components\Host;

$host = new Host('bébé.be');
$domain = Domain::createFromHost($host);
$domain->getContent(); //returns 'xn--bb-bjab.be'

Using a Uri object

The URI must implements League UriInterface or PSR-7 UriInterface.

<?php

use Laminas\Diactoros\Uri as LaminasUri;
use League\Uri\Components\Domain;

$psr7Uri = new LaminasUri("http://www.example.com/path/to/the/sky");

$domain = Domain::createFromUri($psr7Uri);
$domain->getContent(); //return 'www.example.com';

Using a collection of domain labels.

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 Domain::createFromLabels method. The method expects a single arguments, a collection of label. The labels must be ordered hierarchically, this mean that the array should have the top-level domain in its first entry.

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

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

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

Domain::createFromLabels(['0.1', '127.0']);
//throws League\Uri\Exceptions\SyntaxError

The Domain Host API

The following methods can be used to further characterize your domain host.

public Domain::isAbsolute(): bool
public Domain::labels(): array
public Domain::get(int $offset): ?string
public Domain::keys(?string $label = null): array
public Domain::count(): int
public Domain::getIterator(): iterator
public Domain::withRootLabel(): self
public Domain::withoutRootLabel(): self
public Domain::prepend(string $host): self
public Domain::append(string $host): self
public Domain::replaceLabel(int $offset, string $host): self
public Domain::withoutLabels(array $offsets): self

Partial or fully qualified domain name

A host is absolute or 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).

$host = Domain::createFromString('example.com');
$host->isIp();       //return false
$host->isAbsolute(); //return false

$fqdn = Domain::createFromString('example.com.');
$fqdn->isIp();       //return false
$fqdn->isAbsolute(); //return true

Updating the host status

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

withRootLabel
withoutRootLabel

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

$host = Domain::createFromString('www.11.be');
echo $host->withRootLabel() //display 'www.11.be.'
echo $host->withoutRootLabel() //display 'www.11.be'

Normalization

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

the host is lowercased;
the host is converted to its ascii representation;

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

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

The last example depends on the presence of the ext-intl extension. Otherwise the code will trigger a IdnSupportMissing exception

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 Domain::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.

$host = Domain::createFromString('secure.example.com');
$host->labels(); //return  ['com', 'example', 'secure'];

$fqdn = new Domain('secure.example.com.');
$fqdn->labels(); //return ['', 'com', 'example', 'secure'];

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.

$host = Domain::createFromString('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 Domain::keys method.

$host = Domain::createFromString('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 Domain::get method as show below:

$host = Domain::createFromString('example.co.uk');
$host->get(0);  //return 'uk'
$host->get(23); //return null

Domain::get always returns the RFC3987 label representation.

If the offset does not exists it will return null.

Domain::get supports negative offsets

$host = Domain::createFromString('example.co.uk');
$host->get(-1);         //return 'uk'
$host->get(-23);        //return null

Manipulating the host labels

Appending labels

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

$host = Domain::createFromString('toto')->append('example.com');
echo $host; //return toto.example.com

Prepending labels

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

$host = Domain::createFromString('example.com')->prepend('toto');
echo $host; //return toto.example.com

Replacing labels

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

The label’s key to replace if it exists MUST BE an integer.
The data to replace the key with. This data must be a string or null.

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

Just like the Domain::get 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 Domain::withoutLabels method. This method expects variadic integer offset representing the labals offset to remove and will returns a new Host object without the selected labels.

$host    = Domain::createFromString('toto.example.com');
$newHost = $host->withoutLabels(0, 2);
$newHost->__toString(); //return example