Tld Support Laravel Package

Getting Started

Treat layershifter/tld-support as an internal transitive dependency, not the package you adopt directly. In a normal Laravel app you should be using layershifter/tld-extract or layershifter/tld-database; TLDSupport is the shared glue those packages pull in.

Minimal steps:

# Find out why it is installed and which version is locked
composer show layershifter/tld-support
composer why layershifter/tld-support

# For a domain-parsing use case, depend on the higher-level package:
composer require layershifter/tld-extract

Look first at:

• vendor/layershifter/tld-support/src/ to see what is actually public in your locked version.
• The README/source of layershifter/tld-extract or layershifter/tld-database, because those are the intended entry points.
• composer.lock to confirm the exact TLDSupport version and whether it is only present as a transitive dependency.

First practical use case: normalize and inspect a domain submitted by a user, e.g. from a signup form or tenant subdomain:

use LayerShifter\TLDExtract\Extract;

$extract = new Extract();
$result = $extract->parse('https://www.example.co.uk/path');

$host = $result->getHostname();       // www.example.co.uk
$subdomain = $result->getSubdomain(); // www
$domain = $result->getDomain();       // example
$suffix = $result->getSuffix();       // co.uk

$registrableDomain = $domain . '.' . $suffix; // example.co.uk

Verify method names against your locked version before relying on them in application code.

Implementation Patterns

• Do not build directly on TLDSupport unless you are maintaining TLDExtract/TLDDatabase. Its classes are support code and are more likely to change or be replaced than the higher-level package APIs.
• Wrap parsing behind an application service. Keep TLD-specific code in one place so an eventual migration to a maintained parser is a small change.

namespace App\Services;

use LayerShifter\TLDExtract\Extract;

class DomainService
{
    public function __construct(private Extract $extract)
    {
    }

    public function registrableDomain(string $input): ?string
    {
        $input = trim(strtolower($input));
        $input = preg_replace('#^https?://#', '', $input);
        $input = explode('/', $input)[0] ?? $input;
        $input = explode(':', $input)[0] ?? $input;

        $result = $this->extract->parse($input);

        if (! $result || ! $result->getDomain() || ! $result->getSuffix()) {
            return null;
        }

        return $result->getDomain() . '.' . $result->getSuffix();
    }
}

• Use the right layer for the question.
  • “Is this a known TLD?” → TLD database.
  • “What is the registrable domain of foo.bar.co.uk?” → TLD extractor / Public Suffix List logic.
  • “Is this a valid hostname for my app?” → your own validation plus normalization, not TLDSupport alone.
• Normalize before parsing. Lowercase, strip scheme/path/port/userinfo, trim trailing dots deliberately, and convert IDNs consistently. Store the canonical ASCII/punycode form if you accept internationalized domains.
• Use registrable domains for cookies, tenant resolution, and reporting. Subdomain parsing alone breaks on suffixes like co.uk, com.au, and private suffixes such as github.io.
• Bind the parser as a singleton in Laravel if construction loads data:

$this->app->singleton(\LayerShifter\TLDExtract\Extract::class, function () {
    return new \LayerShifter\TLDExtract\Extract();
});

• Add test fixtures for edge cases before trusting it in production: localhost, IP addresses, example.com., uppercase input, [email protected], example.co.uk, foo.blogspot.com, wildcard suffixes, and punycode domains.
• Use it for display and routing decisions, not security boundaries. For anti-phishing or origin checks, combine canonicalization, IDN handling, and your own allow-lists.

Gotchas and Tips

• Archived since 2016. There are no security or compatibility updates, and the bundled TLD/PSL data will be stale. For new work, prefer a maintained domain parser such as jeremykendall/php-domain-parser or bakame/domain-parser.
• TLDSupport is not the product. If composer why shows it is only required by TLDExtract/TLDDatabase, leave it alone. Adding it directly creates unnecessary coupling.
• Public Suffix List ≠ TLD list. co.uk is a public suffix but not a TLD. Do not try to derive registrable domains from a TLD database alone.
• Private suffixes change results. Whether blogspot.com or github.io is treated as a suffix depends on the data and options used. Decide explicitly whether you want private domains included.
• Wildcard and exception rules are easy to get wrong. Rules like *.ck and !www.ck require a real PSL implementation; do not hand-roll suffix matching with explode('.').
• IDN and punycode are a common source of duplicate tenants. example.рф and xn--... may represent the same domain. Normalize once at the boundary and store one canonical form.
• localhost, IPs, ports, and trailing dots often return null/false or unexpected results. Handle them explicitly before calling the parser.
• Debug by inspecting the actual locked source. Use composer show, composer why, and vendor/layershifter/tld-support/src rather than relying on old blog posts or the package README for exact class names.
• If you must extend it, fork and pin. The safest extension point is around the higher-level extractor/database: inject a custom data path or cache if supported, or wrap the parser behind your own interface. Avoid subclassing TLDSupport internals.
• Plan an exit path. Keep TLD parsing behind a small interface so replacing the archived package with a maintained parser is a contained change rather than a codebase-wide refactor.