Skip to content

About

Stringprep (RFC3454), Nameprep (IDNA), Mozilla Public Suffix, parsing domain registries and resolving public suffixes, registrable domains, TLDs, and gTLD metadata with local data registries.

Resources

Stars

0 stars

Watchers

1 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

Codervio Domainparser

Domainparser parses domain registry data and resolves a host name against an IANA TLD list, the Mozilla Public Suffix List, or the ICANN gTLD registry. It supports PHP 8.3 through PHP 8.x and uses Composer for autoloading.

Detailed component documentation is available in docs/.

Highlight features

  • Parse IANA TLD, Mozilla Public Suffix List, ICANN gTLD, Root Zone, IDN Table, RDAP bootstrap, and Special-Use registry data.
  • Resolve public suffixes, registrable domains, subdomains, TLDs, and gTLD metadata.
  • PSL validation with wildcard and exception rules.
  • Domain validation with label-level error messages and error codes.
  • IDN and punycode-aware host normalization when the PHP IDN extension is available.
  • JSON-serializable resolution results for application and API responses.
  • Cached registry files with Composer-based registry refresh support.
  • Deterministic parser APIs that work with downloaded or bundled registry content.
  • Optional DNS lookups that are disabled by default and can be explicitly enabled or forced.
  • Bundled serialized registry snapshots for offline inspection and deterministic processing.

Installation

composer require codervio/domainparser

See Required packages for runtime and development prerequisites.

Resolve a domain with an IANA TLD list

Parser accepts registry data separately from the host being resolved. This makes parsing deterministic and allows applications to cache registry data.

use Codervio\Domainparser\Parser;

$parser = new Parser();
$registry = $parser->parseTld("# Version 2024051800\nCOM\nUK\n");

$parser = new Parser((object) ['records' => $registry['records']]);
$parser->setValue('tld');
$domain = $parser->resolve('www.example.uk');

echo $domain->getPublicSuffix();       // uk
echo $domain->getRegistrableDomain();  // example.uk
echo $domain->getSubDomain();          // www
var_dump($domain->exists());           // true

For a complete public suffix such as co.uk, use the Mozilla suffix registry:

$parser = new Parser();
$parsed = $parser->parseSuffix($mozillaListContents);

$parser = new Parser((object) ['records' => $parsed['records']]);
$parser->setValue('suffix');
$suffix = $parser->resolve('www.example.co.uk');

echo $suffix->getSuffix(); // co.uk

The suffix parser recognizes the ICANN and PRIVATE sections from the Public Suffix List and chooses the longest matching suffix.

Parse and resolve ICANN gTLD metadata

$parser = new Parser();
$parsed = $parser->parseGtlds($jsonContents);

$parser = new Parser((object) ['records' => $parsed['records']]);
$parser->setValue('gtlds');
$gtld = $parser->resolve('www.example');

if ($gtld->exists()) {
    echo $gtld->getGTLD();
    echo $gtld->getRegistryOperator();
}

DNSLookup console preview

┌──────────────────────────── DNSLookup ────────────────────────────┐
│ Host: example.com                                                  │
│ Network: disabled by default — construction makes no DNS request   │
├───────────────────────────────────────────────────────────────────┤
│ enable() / activate()   Explicitly allow lookups                   │
│ getAddresses()          A and AAAA addresses                       │
│ getMailServers()        MX records                                 │
│ getNameServers()        NS records                                 │
│ getTextRecords()        TXT records                                │
│ resolve()               Combined DNS summary                       │
├───────────────────────────────────────────────────────────────────┤
│ Cache: one result per record type for this instance                │
│ Offline tests: inject a resolver callback; no public DNS required │
└───────────────────────────────────────────────────────────────────┘

Bundled registry data

The repository includes cached registry files in src/Registry/:

  • IANA_TLDS.dat — IANA top-level domains.
  • MOZILLA_PUB_SUFFIX.dat — Mozilla Public Suffix List.
  • IANA_GTLDS.json — ICANN gTLD metadata.
  • IANA_ROOT_ZONE.json — serialized IANA Root Zone Database records.
  • IANA_IDN_TABLES.json — serialized IANA IDN table index.
  • IANA_RDAP_DNS.json — serialized RDAP DNS bootstrap services.
  • IANA_SPECIAL_USE.json — serialized RFC/IANA special-use domain names.

Registry source URLs are exposed as constants on RegistryList:

use Codervio\Domainparser\RegistryList;

RegistryList::IANA_TLDS;
RegistryList::MOZILLA_PUB_SUFFIX;
RegistryList::IANA_GTLDS;
RegistryList::IANA_ROOT_ZONE;
RegistryList::IANA_IDN_TABLES;
RegistryList::IANA_RDAP_DNS;
RegistryList::IANA_SPECIAL_USE;

The updatetld Composer command refreshes cached registry files. Network access is required:

composer updatetld

Tests

composer test

Tests cover registry parsing, domain and suffix resolution, gTLD metadata, DNS behavior, cache persistence, registry refresh dispatch, Unicode host normalization, and failure paths.

Required packages

Runtime requirements, enforced by Composer:

  • PHP extensions: mbstring and intl.
  • curl is required when using HTTP registry refreshes, Curl, or updatetld.

For Debian/Ubuntu with PHP 8.3:

sudo apt install php8.3-mbstring php8.3-intl php8.3-curl

For HTML or text coverage reports during development, install PCOV:

sudo apt install php8.3-pcov
php -m | rg pcov

PHP Version support

Domainparser supports PHP 8.3 through PHP 8.x. Composer enforces this with the ^8.3 platform constraint; PHP 9 is not currently declared as supported.

Verify the active runtime and its required extensions with:

php -v
composer check-platform-reqs

Development tools

Install the development dependencies before running the static-analysis and formatting tools:

composer install

Run PHPStan against the source:

vendor/bin/phpstan analyse src --level=5

Preview PHP CS Fixer changes without writing files:

vendor/bin/php-cs-fixer fix src --dry-run --diff

Apply the formatting changes:

vendor/bin/php-cs-fixer fix src --rules=@PSR12

Check PHP Unit:

vendor/bin/phpunit --coverage-text

To run the repository's domain-resolution example:

cd ..
php run.php

License

MIT. See LICENSE.

About

Stringprep (RFC3454), Nameprep (IDNA), Mozilla Public Suffix, parsing domain registries and resolving public suffixes, registrable domains, TLDs, and gTLD metadata with local data registries.

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages