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:

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

Supported TLDs

Specialized parsers with TLD-specific regex patterns:

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

Register parsers in a Service Provider:

<?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:

1. Custom parsers (registered via registerParser()) - highest priority
2. Built-in parsers (auto-discovered from src/Parser/Parsers/)
3. 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