README

A PHP 8.4+ library for querying WHOIS servers and parsing domain registration information. Build raw WHOIS APIs, domain availability checkers, registration info tools, and more.

Features

Direct WHOIS queries - Connects to 70+ WHOIS servers directly (no intermediary web services)
RDAP API support - Use Google's RDAP API for .dev, .app, .page, and other Google Registry TLDs
20 TLD parsers - Specialized parsing for .com, .net, .org, .io, .app, .dev, .ai, .de, .uk, .fr, .ru, and more
Plugin system - Register custom parsers for any TLD from your application code
Smart date parsing - Handles 30+ date formats commonly found in WHOIS responses
IDN support - Automatic punycode conversion for internationalized domain names
Fluent API - Chainable configuration methods
Full type safety - Strict types and modern PHP 8.4 features

Requirements

PHP >= 8.4
ext-intl (optional, for IDN support)

Installation

composer require doyosi/whois

Or clone and install manually:

git clone https://github.com/Doyosi/Doyosi-Whois.git
cd Doyosi-Whois
composer install

Quick Start

<?php

require 'vendor/autoload.php';

use DoyosiWhois\Whois;

$whois = new Whois();
$result = $whois->lookup('example.com');

// Access parsed fields
echo "Domain: " . $result['domain_name'] . "\n";
echo "Registrar: " . $result['registrar'] . "\n";
echo "Created: " . $result['creation_date']->format('Y-m-d') . "\n";
echo "Expires: " . $result['expiration_date']->format('Y-m-d') . "\n";

// Name servers (array)
print_r($result['name_servers']);

// Get all data as array
print_r($result->toArray());

// JSON output
echo json_encode($result, JSON_PRETTY_PRINT);

Configuration

use DoyosiWhois\Whois;

$whois = new Whois();

// Set query timeout (default: 10 seconds)
$whois->setTimeout(15);

// Include raw WHOIS response in results
$whois->includeRaw(true);

// Suppress error logging
$whois->quiet(true);

// Chain configuration
$result = $whois
    ->setTimeout(15)
    ->includeRaw(true)
    ->lookup('example.com');

// Access raw response
echo $result['raw'];

RDAP API (Google Registry TLDs)

For Google Registry TLDs (.dev, .app, .page, .how, .new, .soy, etc.), you can use Google's RDAP API instead of traditional WHOIS. This is especially useful when WHOIS servers are unreachable or return minimal data.

use DoyosiWhois\Whois;

$whois = new Whois();

// Enable RDAP mode for the lookup
$result = $whois
    ->rdap(true)
    ->lookup('example.dev');

// Access parsed data (same format as WHOIS)
echo $result['domain_name'];      // example.dev
echo $result['registrar'];        // Registrar Name
echo $result['expiration_date']->format('Y-m-d');
print_r($result['name_servers']); // ['ns1.example.dev', 'ns2.example.dev']

// Include raw RDAP JSON response
$result = $whois
    ->rdap(true)
    ->includeRaw(true)
    ->lookup('example.dev');

echo $result['raw']; // Pretty-printed JSON

// Check data source
echo $result['data_source']; // 'rdap'

Note: RDAP provides the same parsed fields as WHOIS (domain_name, registrar, dates, name_servers, status, etc.) plus data_source and rdap_url fields.

Custom WHOIS Server / Proxy

Use a local WHOIS proxy or custom server:

use DoyosiWhois\Whois;

$whois = new Whois();

// Use custom WHOIS server (e.g., local proxy)
$result = $whois
    ->useServer('localhost', 43)
    ->lookup('aify.dev');

// Use IP address with custom port
$result = $whois
    ->useServer('217.131.121.202', 43)
    ->includeRaw(true)
    ->lookup('example.com');

// Switch back to auto-detection
$whois->useAutoServer();

Parsed Fields

The library attempts to extract these fields from WHOIS responses:

Field	Type	Description
`domain_name`	string	The domain name
`registrar`	string	Registrar name
`registrar_url`	string	Registrar website
`whois_server`	string	WHOIS server used
`creation_date`	DateTime	Domain registration date
`updated_date`	DateTime	Last update date
`expiration_date`	DateTime	Expiration date
`name_servers`	array	List of name servers
`status`	string\|array	Domain status
`dnssec`	string	DNSSEC status
`emails`	string\|array	Contact emails found
`name`	string	Registrant name
`org`	string	Registrant organization
`country`	string	Registrant country

Note: Field availability varies by TLD and registrar privacy settings.

Supported TLDs

Specialized parsers with TLD-specific regex patterns:

TLD	Parser	Notes
`.com`	WhoisCom	Generic ICANN format
`.net`	WhoisNet	Generic ICANN format
`.org`	WhoisOrg	PIR format
`.info`	WhoisInfo	Afilias format
`.biz`	WhoisBiz	Neustar format
`.io`	WhoisIo	NIC.io format
`.me`	WhoisMe	Domain.me format
`.co`	WhoisCo	.CO Internet format
`.app`	WhoisApp	Google Registry format (use `->rdap(true)` for RDAP API)
`.dev`	WhoisDev	Google Registry format (use `->rdap(true)` for RDAP API)
`.ai`	WhoisAi	Full contact info (registrant, admin, tech, billing)
`.de`	WhoisDe	DENIC format
`.uk`	WhoisUk	Nominet format (day-first dates)
`.fr`	WhoisFr	AFNIC format
`.ru`	WhoisRu	TCINET format
`.au`	WhoisAu	auDA format
`.ca`	WhoisCa	CIRA format
`.nl`	WhoisNl	SIDN format
`.eu`	WhoisEu	EURid format
`.tr`	WhoisTr	NIC.tr format

Other TLDs use the generic parser with standard ICANN patterns.

Custom Parsers (Plugin System)

The library supports custom parsers that you can register from your application code. This is especially useful when:

You need to parse a TLD that isn't built-in
You want to override a built-in parser with custom logic
You're integrating with Laravel or another framework

Basic Registration

use DoyosiWhois\Whois;
use DoyosiWhois\Parser\WhoisEntry;

// Register a parser class
Whois::registerParser('xyz', MyXyzParser::class);

// Register with a callable factory
Whois::registerParser('custom', fn($domain, $text) => new MyCustomParser($domain, $text));

// Register multiple parsers at once
Whois::registerParsers([
    'xyz' => MyXyzParser::class,
    'abc' => MyAbcParser::class,
]);

Creating a Custom Parser

<?php

namespace App\Whois\Parsers;

use DoyosiWhois\Parser\WhoisEntry;

class MyXyzParser extends WhoisEntry
{
    protected array $regex = [
        'domain_name' => '/Domain:\s*(.+)/i',
        'registrar' => '/Registrar:\s*(.+)/i',
        'creation_date' => '/Created:\s*(.+)/i',
        'expiration_date' => '/Expires:\s*(.+)/i',
        'name_servers' => '/NS:\s*(.+)/i',
    ];

    public function __construct(string $domain, string $text)
    {
        if (str_contains($text, 'Not Found')) {
            throw new \DoyosiWhois\Exception\DomainNotFoundException($text);
        }
        parent::__construct($domain, $text);
    }
}

Laravel Integration

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use DoyosiWhois\Whois;
use DoyosiWhois\Parser\ParserRegistry;
use App\Whois\Parsers\MyXyzParser;

class WhoisServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        // Register custom parsers
        Whois::registerParser('xyz', MyXyzParser::class);
        
        // Or use ParserRegistry directly
        ParserRegistry::register('abc', fn($domain, $text) => new MyAbcParser($domain, $text));
    }
}

Parser Priority

When loading a parser, the library checks in this order:

Custom parsers (registered via registerParser()) - highest priority
Built-in parsers (auto-discovered from src/Parser/Parsers/)
Generic WhoisEntry - fallback for unknown TLDs

This means you can override any built-in parser with your own implementation.

List Available TLDs

use DoyosiWhois\Whois;

$tlds = Whois::getAvailableTlds();
// Returns: ['com', 'net', 'org', 'io', 'xyz', ...] (built-in + custom)

Error Handling

use DoyosiWhois\Whois;
use DoyosiWhois\Exception\DomainNotFoundException;
use DoyosiWhois\Exception\UnknownTLDException;
use DoyosiWhois\Exception\WhoisException;

$whois = new Whois();

try {
    $result = $whois->lookup('example.com');
} catch (DomainNotFoundException $e) {
    // Domain does not exist
    echo "Domain not registered\n";
} catch (UnknownTLDException $e) {
    // No WHOIS server found for this TLD
    echo "Unknown TLD\n";
} catch (WhoisException $e) {
    // General WHOIS error (connection, parsing, etc.)
    echo "Error: " . $e->getMessage() . "\n";
}

Raw WHOIS Query

To get just the raw WHOIS response without parsing:

$whois = new Whois();
$rawText = $whois->raw('example.com');
echo $rawText;

Advanced Usage

Domain Extraction

Extract registrable domain from URLs:

use DoyosiWhois\Helpers\DomainExtractor;

$domain = DomainExtractor::extract('https://www.example.com/page?q=test');
// Returns: "example.com"

$domain = DomainExtractor::extract('https://shop.example.co.uk/products');
// Returns: "example.co.uk"

Date Parsing

Parse WHOIS date strings:

use DoyosiWhois\Parser\DateCaster;

$date = DateCaster::cast('2024-03-15T10:30:00Z');
$date = DateCaster::cast('15-Mar-2024');
$date = DateCaster::cast('15/03/2024', dayFirst: true);

echo $date->format('Y-m-d'); // 2024-03-15

Direct Parser Usage

Parse WHOIS text directly:

use DoyosiWhois\Parser\WhoisEntry;

$whoisText = "Domain Name: EXAMPLE.COM\nRegistrar: Example Inc.\n...";
$entry = WhoisEntry::load('example.com', $whoisText);
echo $entry['registrar'];

Testing

composer install
vendor/bin/phpunit tests

Rate Limiting

Warning: WHOIS servers implement rate limiting. Excessive queries may result in temporary IP blocks. Use responsibly and implement appropriate delays between queries.

License

MIT License - see LICENSE for details.

Credits

Original Python implementation: python-whois by Richard Penman
Public Suffix List: publicsuffix.org

doyosi / whois

Maintainers

Details