README

This package provides a mechanism for retrieving a list of the current Top Level Domains (TLDs) managed by IANA. It also provides several Laravel classes to validate domain names and TLDs.

By Simon Hampel

Compatibility

Laravel 9.x - use hampel/tlds 1.10.x
Laravel 10.x - use hampel/tlds 2.x
Laravel 11.x - use hampel/tlds 2.1.x
Laravel 12.x and 13.x - use hampel/tlds 3.x

Requires PHP 8.3 or later.

Installation

To install using composer, run the following command:

composer require hampel/tlds

If you want to change the default Tlds configuration, first publish it using the command:

$ php artisan vendor:publish --provider="Hampel\Tlds\TldServiceProvider"

The config file can then be found in config/tlds.php.

Configuration

tlds.url - the URL to retrieve the data from. By default this is set to the IANA source file

tlds.cache.expiry - sets the cache expiry time in seconds

tlds.cache.key - sets the key used to store the TLD data in the cache

tlds.cache.store - which of your application's configured cache stores to keep the data in. Set to null to use the default store

Usage

The Tlds package reads a data file containing a list of Top Level Domains, one per line, and returns an array of data. This data may optionally be cached for performance.

The data file is retrieved from the Internet Assigned Numbers Authority (IANA) website over HTTP.

The simplest way to call the package is using the Facade:

// get a "fresh" copy of the TLD list
$tld_array = Tlds::fresh();

// or if you prefer to not use Facades:
$tld_array = $app->make(Hampel\Tlds\TldManager::class)->fresh();

This returns a "fresh" copy of the data (bypassing the cache) as an array of TLDs.

To fetch the TLD array from the cache or have it update automatically if the cached data has expired

// get the TLD list from the cache (or update the cache if it has expired)
$tld_array = Tlds::get();

To run the artisan console command to update the cache:

$ php artisan tld:update
Added 725 TLDs to the cache

This is ideal for automating the retrieval of data using a cron job or similar.

Any line in the source data that is not a valid TLD is skipped, and reported by the console command:

$ php artisan tld:update
Skipped [not-a-tld!] - did not match the TLD format
Added 724 TLDs to the cache

Reading the TLD list from somewhere else

To read the list from a local file, an internal mirror, or any other source, implement Hampel\Tlds\Fetcher\TldFetcher and bind it in your application's service provider. The tlds.url setting is then unused.

use Hampel\Tlds\Fetcher\TldFetcher;

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->bind(TldFetcher::class, MyTldFetcher::class);
    }
}

The interface has a single method, which returns the raw file contents as a string:

use Hampel\Tlds\Exceptions\FetchException;
use Hampel\Tlds\Fetcher\TldFetcher;

class MyTldFetcher implements TldFetcher
{
    public function fetchTlds()
    {
        // throw a FetchException, or a subclass of it, if the data cannot be retrieved
        return file_get_contents('/path/to/tlds-alpha-by-domain.txt');
    }
}

The source data format is assumed to be:

one TLD per line
either upper or lower case
lines beginning with # are ignored
internationalized domains allowed using punycode notation

Validators

This package adds additional validators for Laravel - refer to Laravel Documentation - Validation for general usage instructions.

Domain

The field under validation must be a valid domain name. The Top Level Domain (TLD) is checked against a list of all acceptable TLDs, including internationalised domains in punycode notation

Example:

use Hampel\Tlds\Validation\Domain;

// valid values: example.com; example.au
// invalid values: example.invalid-tld

$request->validate([
    'domain' => ['required', 'string', new Domain],
]);

DomainIn([<array of TLDs>])

The field under validation must be a valid domain with a TLD from one of the specified options

Example:

use Hampel\Tlds\Validation\DomainIn;

// valid values: example.com; example.net
// invalid values: example.co; example.au (not in specified list of domain TLDs)

$request->validate([
    'domain' => ['required', 'string', new DomainIn(['com', 'net'])],
]);

Tld

The field under validation must end in a valid Top Level Domain (TLD). The TLD is checked against a list of all acceptable TLDs, including internationalised domains in punycode notation

If no dots are contained in the supplied value, it will be assumed to be only a TLD.

If the value contains dots, only the part after the last dot will be validated.

Example:

use Hampel\Tlds\Validation\Tld;

// valid values: example.com; com; net (either a domain with a valid TLD, or a string that is itself a valid TLD)
// invalid values: example.invalid-tld; something-not-a-tld

$request->validate([
    'domain' => ['required', 'string', new Tld],
]);

TldIn([<array of TLDs>])

The field under validation must end in a TLD from one of the specified options

If no dots are contained in the supplied value, it will be assumed to be only a TLD.

If the value contains dots, only the part after the last dot will be validated.

Example:

use Hampel\Tlds\Validation\TldIn;

// valid values: example.com; example.net; com; net
// invalid values: example.co; org (not in specified list of domain TLDs)

$request->validate([
    'domain' => ['required', 'string', new TldIn(['com', 'net'])],
]);

hampel / tlds

Package info

Security

Statistics

README

Compatibility

Installation

Configuration

Usage

Reading the TLD list from somewhere else

Validators