PHP code example of jeremykendall / php-domain-parser

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

jeremykendall / php-domain-parser example snippets

 
use Pdp\Rules;
use Pdp\Domain;

$publicSuffixList = Rules::fromPath('/path/to/cache/public-suffix-list.dat');
$domain = Domain::fromIDNA2008('www.PreF.OkiNawA.jP');

$result = $publicSuffixList->resolve($domain);
echo $result->domain()->toString();            //display 'www.pref.okinawa.jp';
echo $result->subDomain()->toString();         //display 'www';
echo $result->secondLevelDomain()->toString(); //display 'pref';
echo $result->registrableDomain()->toString(); //display 'pref.okinawa.jp';
echo $result->suffix()->toString();            //display 'okinawa.jp';
$result->suffix()->isICANN();                  //return true;
~~~

For the [IANA Top Level Domain List](https://www.iana.org/domains/root/files),
the `Pdp\TopLevelDomains` class is use instead:

~~~php


use Pdp\Domain;
use Pdp\TopLevelDomains;

$topLevelDomains = TopLevelDomains::fromPath('/path/to/cache/tlds-alpha-by-domain.txt');
$domain = Domain::fromIDNA2008('www.PreF.OkiNawA.jP');

$result = $topLevelDomains->resolve($domain);
echo $result->domain()->toString();            //display 'www.pref.okinawa.jp';
echo $result->suffix()->toString();            //display 'jp';
echo $result->secondLevelDomain()->toString(); //display 'okinawa';
echo $result->registrableDomain()->toString(); //display 'okinawa.jp';
echo $result->subDomain()->toString();         //display 'www.pref';
echo $result->suffix()->isIANA();              //return true
~~~

In case of an error an exception which extends `Pdp\CannotProcessHost` is thrown.

The `resolve` method will always return a `ResolvedDomain` even if the domain
syntax is invalid or if there is no match found in the resource data. 
To work around this limitation, the library exposes more strict methods,
namely:

- `Rules::getCookieDomain`
- `Rules::getICANNDomain`
- `Rules::getPrivateDomain`

for the Public Suffix List and the following method for the Top Level
Domain List:

- `TopLevelDomains::getIANADomain`

These methods resolve the domain against their respective data source using
the same rules as the `resolve` method but will instead throw an exception 
if no valid effective TLD is found or if the submitted domain is invalid.

> [!CAUTION]
> All these methods expect as their sole argument a `Pdp\Host` implementing 
object, but other types (ie: `string`, `null`  and stringable objects) are 
supported with predefined conditions as explained in the remaining document.

~~~php


use Pdp\Domain;
use Pdp\Rules;
use Pdp\TopLevelDomains;

$publicSuffixList = Rules::fromPath('/path/to/cache/public-suffix-list.dat');
$domain = Domain::fromIDNA2008('qfdsf.unknownTLD');

$publicSuffixList->getICANNDomain($domain);
// will throw because `.unknownTLD` is not part of the ICANN section

$result = $publicSuffixList->getCookieDomain($domain);
$result->suffix()->value();   // returns 'unknownTLD'
$result->suffix()->isKnown(); // returns false
// will not throw because the domain syntax is correct.

$publicSuffixList->getCookieDomain(Domain::fromIDNA2008('com'));
// will not throw because the domain syntax is invalid (ie: does not support public suffix)

$result = $publicSuffixList->resolve(Domain::fromIDNA2008('com'));
$result->suffix()->value();   // returns null
$result->suffix()->isKnown(); // returns false
// will not throw but its public suffix value equal to NULL

$topLevelDomains = TopLevelDomains::fromPath('/path/to/cache/public-suffix-list.dat');
$topLevelDomains->getIANADomain(Domain::fromIDNA2008('com'));
// will not throw because the domain syntax is invalid (ie: does not support public suffix)
~~~

To instantiate each domain resolver you can use the following named constructor:

- `fromString`: instantiate the resolver from a inline string representing the data source;
- `fromPath`: instantiate the resolver from a local path or online URL by relying on `fopen`;

**If the instantiation does not work an exception will be thrown.**

> [!WARNING]
> You SHOULD never resolve domain name this way in production, without, at 
least, a caching mechanism to reduce external resource downloads.
> Using the Public Suffix List to determine what is a valid domain name and what 
isn't is dangerous, and MAY lead to errors because of new gTLDs being registered
on a regular basis.
> If you are looking to know the validity of a Top Level Domain, you MUST use
the IANA Top Level Domain List as the proper source for this information or 
alternatively the DNS.
> If you MUST use this library for any of the above purposes, you SHOULD consider 
integrating an updating mechanism into your software.
> For more information go to the [Managing external data source section](#managing-the-package-external-resources)** 

### Resolved domain information.

Whichever methods chosen to resolve the domain on success, the package will
return a `Pdp\ResolvedDomain` instance.

The `Pdp\ResolvedDomain` decorates the `Pdp\Domain` class resolved but also 
gives access as separate methods to the domain different components.

~~~php
use Pdp\Domain;
use Pdp\TopLevelDomains;

$domain = Domain::fromIDNA2008('www.PreF.OkiNawA.jP');
/** @var TopLevelDomains $topLevelDomains */
$result = $topLevelDomains->resolve($domain);
echo $result->domain()->toString();            //display 'www.pref.okinawa.jp';
echo $result->suffix()->toString();            //display 'jp';
echo $result->secondLevelDomain()->toString(); //display 'okinawa';
echo $result->registrableDomain()->toString(); //display 'okinawa.jp';
echo $result->subDomain()->toString();         //display 'www.pref';
echo $result->suffix()->isIANA();              //return true
~~~
 
You can modify the returned `Pdp\ResolvedDomain` instance using the following methods:

~~~php
 

use Pdp\Domain;
use Pdp\Rules;

/** @var Rules $publicSuffixList */
$result = $publicSuffixList->resolve(Domain::fromIDNA2008('shop.example.com'));
$altResult = $result
    ->withSubDomain(Domain::fromIDNA2008('foo.bar'))
    ->withSecondLevelDomain(Domain::fromIDNA2008('test'))
    ->withSuffix(Domain::fromIDNA2008('example'));

echo $result->domain()->toString(); //display 'shop.example.com';
$result->suffix()->isKnown();       //return true;

echo $altResult->domain()->toString(); //display 'foo.bar.test.example';
$altResult->suffix()->isKnown();       //return false;
~~~

> [!TIP]
> Always favor submitting a `Pdp\Suffix` object rather that any other
supported type to avoid unexpected results. By default, if the input is not a
`Pdp\Suffix` instance, the resulting public suffix will be labelled as
being unknown. For more information go to the [Public Suffix section](#public-suffix)

### Domain Suffix

The domain effective TLD is represented using the `Pdp\Suffix`. Depending on
the data source the object exposes different information regarding its
origin.

~~~php
 
use Pdp\Domain;
use Pdp\Rules;

/** @var Rules $publicSuffixList */
$suffix = $publicSuffixList->resolve(Domain::fromIDNA2008('example.github.io'))->suffix();

echo $suffix->domain()->toString(); //display 'github.io';
$suffix->isICANN();                 //will return false
$suffix->isPrivate();               //will return true
$suffix->isPublicSuffix();          //will return true
$suffix->isIANA();                  //will return false
$suffix->isKnown();                 //will return true
~~~

The public suffix state depends on its origin:
 
- `isKnown` returns `true` if the value is present in the data resource.
- `isIANA` returns `true` if the value is present in the IANA Top Level Domain List.
- `isPublicSuffix` returns `true` if the value is present in the Public Suffix List.
- `isICANN` returns `true` if the value is present in the Public Suffix List ICANN section.
- `isPrivate` returns `true` if the value is present in the Public Suffix List private section.
 
The same information is used when `Pdp\Suffix` object is 
instantiate via its named constructors:
 
 ~~~php
  
 use Pdp\Suffix;

$iana = Suffix::fromIANA('ac.be');
$icann = Suffix::fromICANN('ac.be');
$private = Suffix::fromPrivate('ac.be');
$unknown = Suffix::fromUnknown('ac.be');
~~~

Using a `Suffix` object instead of a string or `null` with 
`ResolvedDomain::withSuffix` will ensure that the returned value will
always contain the correct information regarding the public suffix resolution.
 
Using a `Domain` object instead of a string or `null` with the named 
constructor ensure a better instantiation of the Public Suffix object for
more information go to the [ASCII and Unicode format section](#ascii-and-unicode-formats) 
 
### Accessing and processing Domain labels

If you are interested into manipulating the domain labels without taking into 
account the Effective TLD, the library provides a `Domain` object tailored for
manipulating domain labels. You can access the object using the following methods:
 
- the `ResolvedDomain::domain` method 
- the `ResolvedDomain::subDomain` method
- the `ResolvedDomain::registrableDomain` method
- the `ResolvedDomain::secondLevelDomain` method
- the `Suffix::domain` method

`Domain` objects usage are explain in the next section.

~~~php

use Pdp\Domain;
use Pdp\Rules;

/** @var Rules $publicSuffixList */
$result = $publicSuffixList->resolve(Domain::from2008('www.bbc.co.uk'));
$domain = $result->domain();
echo $domain->toString(); // display 'www.bbc.co.uk'
count($domain);           // returns 4
$domain->labels();        // returns ['uk', 'co', 'bbc', 'www'];
$domain->label(-1);       // returns 'www'
$domain->label(0);        // returns 'uk'
foreach ($domain as $label) {
   echo $label, PHP_EOL;