Download the PHP package hampel/tlds without Composer

Top Level Domain Fetcher for Laravel

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:

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:

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

To run the artisan console command to update 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:

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.

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

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:

DomainIn([<array of TLDs>])

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

Example:

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:

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: