bakame/laravel-domain-parser

Laravel package to integrate PHP Domain parser.

0.3.0 2018-12-13 14:50 UTC

README

Author Build Status Total Downloads Latest Stable Version Software License

A Laravel package to ease PHP Domain Parser v5.4+ integration in your Laravel application.

Usage

Once installed and configured, in your Laravel application, you will be able to:

use the following facades:

$domain = Rules::resolve('www.ulb.ac.be'); //$domain is a Pdp\Domain object
echo $domain->getContent();            // 'www.ulb.ac.be'
echo $domain->getPublicSuffix();       // 'ac.be'
echo $domain->getRegistrableDomain();  // 'ulb.ac.be'
echo $domain->getSubDomain();          // 'www'
$domain->isResolvable();               // returns true
$domain->isKnown();                    // returns true
$domain->isICANN();                    // returns true
$domain->isPrivate();                  // returns false

TopLevelDomains::contains('localhost'); // return false

Access additional validation rules:

$validator = Validator::make($request->all(), [
    'tld' => 'is_tld',
    'domain' => 'is_icann_suffix',
]);

//or

$request->validate([
    'tld' => 'required|is_tld',
    'domain' => 'required|is_icann_suffix',
]);

Use conditionnal Blade directives:

@contains_tld('example.localhost')
OK
@else
KO
@endcontains_tld
{{-- KO --}}

@domain_to_unicode('www.xn--85x722f.xn--55qx5d.cn') {{-- www.食狮.公司.cn --}}
@domain_to_ascii('www.食狮.公司.cn') {{-- www.xn--85x722f.xn--55qx5d.cn --}}

System Requirements

You need:

  • PHP >= 7.1.3 but the latest stable version of PHP is recommended
  • you need Laravel 5.5 but the latest stable version is recommended

Installation

$ composer require bakame/laravel-domain-parser

The package will automatically register itself.

Configuration

This is the contents of the published config file

return [
    /**
     * Name of the cache to use. If a string is given it will be one of
     * the store listed in the `stores` configuration array in
     * your `cache` configuration file.
     */
    'cache_client' => 'file',
    /**
     * Cache TTL.
     * - Can be a DateInterval object
     * - If a DateTimeInterface object is given, the TTL will represents
     *   the difference between the given object and the current timestamp
     * - If a string is given is must be usable by DateInterval::createFromDateString
     * - If an int is given, it is consireded as the TTL is seconds
     */
    'cache_ttl' => '1 DAY',
    /**
     * Name of the HTTP Client to use. If a string is given it must be of
     * of the following curl, guzzle.
     * Otherwise you can give an instance of a Pdp\HttpClient implementing object.
     */
    'http_client' => 'curl',
    /**
     * HTTP client options (optional).
     * Additionals options to use when instantiating the curl and/or the guzzle client
     * For the curl client the options takes a array usable by curl_setopt_array
     * For the guzzle client the options will be used on instantiation
     * Not use or check if a Pdp\HttpClient implementing object is given to http_client.
     */
    'http_client_options' => [],
    /**
     * External Public Suffix List URL (optional)
     * If not present or equals to `null` the package will default to the official URL
     */
    'url_psl' => 'https://publicsuffix.org/list/public_suffix_list.dat',
    /**
     * External Root Zone Database URL (optional)
     * If not present or equals to `null` the package will default to the official URL
     */
    'url_rzd' => 'https://data.iana.org/TLD/tlds-alpha-by-domain.txt',
];

Documentation

Validation rules

Rules Description
is_domain_name Tells whether the submitted value represents a Domain Name
is_tld Tells whether the submitted value is a TLD
contains_tld Tells whether the submitted value is a Domain Name with a known TLD
is_known_suffix Tells whether the submitted value is a Domain Name with a known suffix
is_icann_suffix Tells whether the submitted value is a Domain Name with an ICANN suffix
is_private_suffix Tells whether the submitted value is a Domain Name with a Private suffix

Blade if statement directives

If statement Description
domain_name Tells whether the submitted value represents a Domain Name
tld Tells whether the submitted value is a TLD
contains_tld Tells whether the submitted value is a Domain Name with a known TLD
known_suffix Tells whether the submitted value is a Domain Name with a Known suffix
icann_suffix Tells whether the submitted value is a Domain Name with an ICANN suffix
private_suffix Tells whether the submitted value is a Domain Name with a Private suffix

Blade directives

directive Description
domain_to_unicode Converts the hostname into its Unicode representation
domain_to_ascii Converts the hostname into its Ascii representation

Facades

  • Rules is a Laravel Facade for Pdp\Rules loaded using the configuration files settings.
  • TopLevelDomains is a Laravel Facade for Pdp\TopLevelDomains loaded using the configuration files settings.

Maintenance

Refresh Cache Command

You can warm and/or update the cache information using the bundled refresh cache command manually. You can choose to refresh:

  • the Public Suffix List
php artisan domain-parser:refresh --rules
  • the IANA Root Zone Database
php artisan domain-parser:refresh --tlds
  • both set of data in a single call (default action)
php artisan domain-parser:refresh

Scheduling

It is, however, recommended to schedule this command so you don't have to manually run domain-parser:resfresh everytime you need to update your cache or directly when a user interact with your application on production.

The command can be scheduled in Laravel's console kernel, just like any other command.

// app/Console/Kernel.php
protected function schedule(Schedule $schedule)
{
   $schedule->command('domain-parser:refresh')->daily()->at('04:00');
}

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Contributions are welcome and will be fully credited. Please see CONTRIBUTING and CONDUCT for details.

Testing

The library has a :

  • a PHPUnit test suite
  • a coding style compliance test suite using PHP CS Fixer.
  • a code analysis compliance test suite using PHPStan.

To run the tests, run the following command from the project folder.

$ composer test

Security

If you discover any security related issues, please email nyamsprod@gmail.com instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.