Prefix WhoIs from PHP.

<?php/** * Prefix WhoIs client library for PHP * * A small, dependency-free client for the Prefix WhoIs service (whois.pwhois.org): * one address at a time, or up to 500 per round trip in bulk mode. Answers come back * as arrays keyed by the field names the server uses, lower-cased ("origin-as", * "as-org-name", "prefix", "country-code", ...). * *   require 'pwhois.php'; * *   $one  = pwhois_lookup('4.2.2.1');                 // ?array *   $many = pwhois_lookup_bulk(['4.2.2.1', '2001:4860:4860::8888', '10.0.0.1']); *   //  => ['4.2.2.1' => [...], '2001:4860:4860::8888' => [...], '10.0.0.1' => null] * *   pwhois_cache_enable();                            // optional: 24-hour LRU cache (SQLite, built into PHP) *   $q = pwhois_quota();                              // your address's daily limit, used, remaining * * Every query costs one unit of your daily allowance, so the library never asks twice: * duplicates in a batch are collapsed, and with the cache enabled an address already * answered today is served from disk. Requires PHP 7.4 or later (8.x recommended) with * stream sockets; nothing else. Public service limits apply: 5,000 queries per source * address per day by default. Higher limits are customarily granted free upon reasonable * request; see https://pwhois.org/contact.who?contact=request * * Copyright (c) 2005-2026 VOSTROM Holdings, Inc. Released under the same open source * license as the Prefix WhoIs software; see https://pwhois.org/license.who */declare(strict_types=1);const PWHOIS_SERVER        = 'whois.pwhois.org';const PWHOIS_PORT          = 43;const PWHOIS_APP           = 'pwhois.php/2.0';const PWHOIS_USER_AGENT    = 'pwhois.php/2.0 (VOSTROM; +https://pwhois.org/php.who)';const PWHOIS_BULK_MAX      = 500;     // addresses per round trip; the server accepts more, this keeps answers promptconst PWHOIS_CONNECT_SECS  = 10;      // connect timeoutconst PWHOIS_READ_SECS     = 20;      // overall read deadline per round tripconst PWHOIS_MAX_BYTES     = 4 << 20; // 4 MB answer cap per round trip/** * Look up one IPv4 or IPv6 address. * * Returns the record as [field => value], or null when the address is invalid, the * server could not be reached, or it had nothing to say (unrouted, unregistered space). * Values the server marks NULL are returned as PHP null. $options: 'app' (string shown * in the server's statistics), 'type' ('pwhois' default, or 'all' for the registry * record too), 'server', 'port'. */function pwhois_lookup(string $address, array $options = []): ?array{    $ip = pwhois_normalize_ip($address);    if ($ip === null) return null;    $type = ($options['type'] ?? 'pwhois') === 'all' ? 'all' : 'pwhois';    $hit = pwhois_cache_get($ip, $type);    if ($hit !== false) return $hit;    $raw = pwhois_transact(pwhois_request_header($options) . ($type === 'all' ? 'type=all ' : '') . $ip . "\n", $options);    if ($raw === null) return null;    pwhois_usage_count(1);    $records = pwhois_parse($raw);    $rec = ($records && pwhois_has_content($records[0])) ? $records[0] : null;    pwhois_cache_put($ip, $type, $rec);    return $rec;}/** True when the server knows the address: it is routed or registered. Unrouted, unregistered space comes back as all NULL (plus zero coordinates). */function pwhois_has_content(array $rec): bool{    foreach (['origin-as', 'prefix', 'org-name', 'net-name', 'as-org-name', 'org-id', 'net-range'] as $k) if (($rec[$k] ?? null) !== null) return true;    return false;}/** * Look up many addresses in bulk mode. Duplicates are collapsed, invalid entries are * reported as null, and the result is keyed by the address exactly as you passed it. * * Returns [address => record|null]. Returns null only when no round trip could be * completed at all (connection failure); a partial failure leaves the missing * addresses null and sets $options['errors'] (by reference) with a message per batch. */function pwhois_lookup_bulk(array $addresses, ?array &$options = null): ?array{    $options = $options ?? [];    $result = []; $byIp = []; $order = [];    foreach ($addresses as $a) {        if (!is_string($a) && !is_int($a)) continue;        $key = (string) $a; $ip = pwhois_normalize_ip($key);        $result[$key] = null;        if ($ip === null) continue;        if (!isset($byIp[$ip])) { $byIp[$ip] = []; $order[] = $ip; }        $byIp[$ip][] = $key;    }    if (!$order) return $result;    // Serve what the cache already knows; only the rest goes to the server.    $pending = [];    foreach ($order as $ip) {        $hit = pwhois_cache_get($ip, 'pwhois');        if ($hit !== false) { foreach ($byIp[$ip] as $key) $result[$key] = $hit; } else $pending[] = $ip;    }    $options['cached'] = count($order) - count($pending);    $errors = []; $completed = 0;    if (!$pending) { $options['errors'] = []; return $result; }    foreach (array_chunk($pending, (int) ($options['batch'] ?? PWHOIS_BULK_MAX)) as $n => $chunk) {        $raw = pwhois_transact(pwhois_request_header($options) . "begin\n" . implode("\n", $chunk) . "\nend\n", $options);        if ($raw === null) { $errors[] = 'batch ' . ($n + 1) . ': no answer from the server'; continue; }        $completed++; pwhois_usage_count(count($chunk));        $seen = [];        foreach (pwhois_parse($raw) as $rec) {            $ip = pwhois_normalize_ip((string) ($rec['ip'] ?? ''));            if ($ip === null || !isset($byIp[$ip])) continue;            $val = pwhois_has_content($rec) ? $rec : null; $seen[$ip] = true;            foreach ($byIp[$ip] as $key) $result[$key] = $val;            pwhois_cache_put($ip, 'pwhois', $val);        }        foreach ($chunk as $ip) if (!isset($seen[$ip])) pwhois_cache_put($ip, 'pwhois', null);   // the server said nothing: unrouted    }    $options['errors'] = $errors;    return $completed === 0 ? null : $result;}/** Canonical text of a valid IPv4/IPv6 address, or null. A trailing /bits is dropped. */function pwhois_normalize_ip(string $s): ?string{    $s = trim($s);    if ($s === '') return null;    $s = (string) preg_replace('~/\d{1,3}$~', '', $s);    if (!filter_var($s, FILTER_VALIDATE_IP)) return null;    $bin = @inet_pton($s);    return $bin === false ? null : (string) inet_ntop($bin);}/** The app= line that identifies this client in the server's statistics. */function pwhois_request_header(array $options): string{    $app = (string) ($options['app'] ?? PWHOIS_APP);    $app = (string) preg_replace('/[^\x20-\x7e]/', '', str_replace('"', '', $app));    return 'app="' . substr($app, 0, 60) . "\"\n";}/** * One connection, one request, the whole answer. Returns the raw text or null. * The server is reached over IPv4 on purpose: the public service authorizes IPv4 * sources for bulk mode, and a hostname that also has an AAAA record would otherwise * be tried over IPv6 first. */function pwhois_transact(string $request, array $options = []): ?string{    $host = (string) ($options['server'] ?? PWHOIS_SERVER);    $port = (int) ($options['port'] ?? PWHOIS_PORT);    $addr = filter_var($host, FILTER_VALIDATE_IP) ? $host : gethostbyname($host);    if (!filter_var($addr, FILTER_VALIDATE_IP, FILTER_FLAG_IPV4)) return null;    $sock = @stream_socket_client('tcp://' . $addr . ':' . $port, $errno, $errstr, PWHOIS_CONNECT_SECS);    if (!$sock) return null;    stream_set_timeout($sock, PWHOIS_READ_SECS);    if (@fwrite($sock, $request) === false) { fclose($sock); return null; }    $buf = ''; $deadline = microtime(true) + PWHOIS_READ_SECS;    while (!feof($sock) && microtime(true) < $deadline) {        $chunk = fread($sock, 65536);        if ($chunk === false) break;        if ($chunk === '') { $meta = stream_get_meta_data($sock); if (!empty($meta['timed_out'])) break; continue; }        $buf .= $chunk;        if (strlen($buf) > PWHOIS_MAX_BYTES) break;    }    fclose($sock);    return $buf === '' ? null : $buf;}/** * Parse the server's "Field: value" text into records. Records are separated by blank * lines or by a new "IP:" line. Only the first colon splits a line, so IPv6 values * survive. Field names are lower-cased with their hyphens kept ("origin-as"). */function pwhois_parse(string $raw): array{    $records = []; $cur = [];    foreach (preg_split('/\r?\n/', $raw) ?: [] as $line) {        if (trim($line) === '') { if ($cur) { $records[] = $cur; $cur = []; } continue; }        if (stripos($line, 'Error:') === 0) continue;        $p = strpos($line, ':');        if ($p === false) continue;        $key = strtolower(trim(substr($line, 0, $p)));        if ($key === '' || !preg_match('/^[a-z0-9 _-]+$/', $key)) continue;        $key = str_replace(' ', '-', $key);        if ($key === 'ip' && $cur) { $records[] = $cur; $cur = []; }        $cur[$key] = pwhois_clean_value(substr($line, $p + 1));    }    if ($cur) $records[] = $cur;    return $records;}/** Trim, map the server's NULL sentinel to null, and drop anything that is not printable text. */function pwhois_clean_value(string $v): ?string{    $v = trim($v);    if ($v === '' || strcasecmp($v, 'NULL') === 0) return null;    $v = (string) preg_replace('/[^\P{C}]/u', '', $v);    // Registry text is occasionally polluted (e.g. a pasted token after an org name); keep the name, drop the blob.    $v = (string) preg_split('/\s*-{2,}\s*BEGIN\b/i', $v, 2)[0];    $v = (string) preg_replace('/\b[0-9a-fA-F]{32,}\b/', '', $v);    $v = trim((string) preg_replace('/\s{2,}/', ' ', $v));    return $v === '' ? null : $v;}/* ---------------------------------------------------------------------------------   Optional 24-hour cache. Off until you enable it.   Backend: SQLite through PDO (part of PHP itself, nothing to install). Every process   and application sharing the file gets real row-level upserts and SQLite's own locking,   so concurrent writers are safe; expiry and least-recently-used eviction are indexed   columns. Where pdo_sqlite is unavailable, a directory of one small file per address   is used instead (atomic renames, no shared write contention).   --------------------------------------------------------------------------------- *//** * Enable the cache. $path defaults to <system temp dir>/pwhois-cache.sqlite; give a * directory (existing, or ending in "/") to force the file-per-address backend. $ttl is * the lifetime of an answer in seconds (a day); $max the number of addresses kept. * Negative answers (unrouted space) are cached too, so they are not asked again either. */function pwhois_cache_enable(?string $path = null, int $ttl = 86400, int $max = 20000): void{    $c = &pwhois_state();    $path = $path ?? rtrim(sys_get_temp_dir(), '/') . '/pwhois-cache.sqlite';    $useDir = is_dir($path) || substr($path, -1) === '/' || !class_exists('PDO') || !in_array('sqlite', PDO::getAvailableDrivers(), true);    if (!$useDir && !is_dir(dirname($path))) @mkdir(dirname($path), 0700, true);    $c['cache'] = ['mode' => $useDir ? 'dir' : 'sqlite', 'path' => rtrim($path, '/'), 'ttl' => max(60, $ttl), 'max' => max(100, $max), 'pdo' => null, 'hits' => 0, 'misses' => 0, 'writes' => 0];    if ($useDir && !is_dir($c['cache']['path'])) @mkdir($c['cache']['path'], 0700, true);}function pwhois_cache_disable(): void { $c = &pwhois_state(); $c['cache'] = null; }/** Hits, misses, writes and entries so far; null when the cache is off. */function pwhois_cache_stats(): ?array{    $c = &pwhois_state(); if (!$c['cache']) return null;    $n = 0;    if ($c['cache']['mode'] === 'sqlite') { $pdo = pwhois_cache_pdo(); if ($pdo) { try { $n = (int) $pdo->query('SELECT COUNT(*) FROM pwhois_cache')->fetchColumn(); } catch (Throwable $e) { } } }    else { foreach (new DirectoryIterator($c['cache']['path']) as $f) if ($f->isFile() && substr($f->getFilename(), -5) === '.json') $n++; }    return ['backend' => $c['cache']['mode'], 'path' => $c['cache']['path'], 'ttl' => $c['cache']['ttl'], 'entries' => $n, 'hits' => $c['cache']['hits'], 'misses' => $c['cache']['misses'], 'writes' => $c['cache']['writes']];}/** Remove expired rows and, if over $max, the least recently used. Runs automatically about once per 500 writes. */function pwhois_cache_prune(): void{    $c = &pwhois_state(); if (!$c['cache']) return;    $now = time(); $cut = $now - $c['cache']['ttl'];    if ($c['cache']['mode'] === 'sqlite') {        $pdo = pwhois_cache_pdo(); if (!$pdo) return;        try {            $pdo->prepare('DELETE FROM pwhois_cache WHERE stored < :cut')->execute([':cut' => $cut]);            $n = (int) $pdo->query('SELECT COUNT(*) FROM pwhois_cache')->fetchColumn();            if ($n > $c['cache']['max']) { $st = $pdo->prepare('DELETE FROM pwhois_cache WHERE k IN (SELECT k FROM pwhois_cache ORDER BY used ASC LIMIT :n)'); $st->bindValue(':n', $n - $c['cache']['max'], PDO::PARAM_INT); $st->execute(); }        } catch (Throwable $e) { }    } else {        $files = [];        foreach (new DirectoryIterator($c['cache']['path']) as $f) { if (!$f->isFile() || substr($f->getFilename(), -5) !== '.json') continue; $m = $f->getMTime(); if ($m < $cut) @unlink($f->getPathname()); else $files[$f->getPathname()] = $m; }        if (count($files) > $c['cache']['max']) { asort($files); foreach (array_slice(array_keys($files), 0, count($files) - $c['cache']['max']) as $fp) @unlink($fp); }    }}/** @internal shared state */function &pwhois_state(): array{    static $state = ['cache' => null, 'usage' => null];    return $state;}/** @internal open (and on first use create) the SQLite cache */function pwhois_cache_pdo(): ?PDO{    $c = &pwhois_state(); if (!$c['cache'] || $c['cache']['mode'] !== 'sqlite') return null;    if ($c['cache']['pdo'] instanceof PDO) return $c['cache']['pdo'];    try {        $pdo = new PDO('sqlite:' . $c['cache']['path'], null, null, [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION, PDO::ATTR_TIMEOUT => 5]);        $pdo->exec('PRAGMA journal_mode=WAL'); $pdo->exec('PRAGMA synchronous=NORMAL'); $pdo->exec('PRAGMA busy_timeout=5000');        $pdo->exec('CREATE TABLE IF NOT EXISTS pwhois_cache (k TEXT PRIMARY KEY, stored INTEGER NOT NULL, used INTEGER NOT NULL, rec TEXT)');        $pdo->exec('CREATE INDEX IF NOT EXISTS pwhois_cache_used ON pwhois_cache(used)');        $pdo->exec('CREATE INDEX IF NOT EXISTS pwhois_cache_stored ON pwhois_cache(stored)');        return $c['cache']['pdo'] = $pdo;    } catch (Throwable $e) { $c['cache']['mode'] = 'dir'; $c['cache']['path'] .= '.d'; @mkdir($c['cache']['path'], 0700, true); return null; }   // fall back to files}/** @internal file name for an entry in directory mode */function pwhois_cache_file(string $k): string { $c = &pwhois_state(); return $c['cache']['path'] . '/' . hash('sha256', $k) . '.json'; }/** Returns the cached record (array or null) or false when absent/expired. */function pwhois_cache_get(string $ip, string $type){    $c = &pwhois_state(); if (!$c['cache']) return false;    $k = $type . ':' . $ip; $now = time(); $cut = $now - $c['cache']['ttl'];    if ($c['cache']['mode'] === 'sqlite' && ($pdo = pwhois_cache_pdo())) {        try {            $st = $pdo->prepare('SELECT stored, rec FROM pwhois_cache WHERE k = :k'); $st->execute([':k' => $k]); $row = $st->fetch(PDO::FETCH_ASSOC);            if (!$row || (int) $row['stored'] < $cut) { $c['cache']['misses']++; return false; }            if ($now - (int) ($row['used'] ?? 0) > 60) $pdo->prepare('UPDATE pwhois_cache SET used = :u WHERE k = :k')->execute([':u' => $now, ':k' => $k]);            $c['cache']['hits']++; $rec = json_decode((string) $row['rec'], true); return is_array($rec) ? $rec : null;        } catch (Throwable $e) { $c['cache']['misses']++; return false; }    }    $f = pwhois_cache_file($k);    if (!is_file($f) || (int) @filemtime($f) < $cut) { $c['cache']['misses']++; return false; }    $j = json_decode((string) @file_get_contents($f), true);    if (!is_array($j) || !array_key_exists('r', $j)) { $c['cache']['misses']++; return false; }    @touch($f); $c['cache']['hits']++; return $j['r'];}function pwhois_cache_put(string $ip, string $type, ?array $rec): void{    $c = &pwhois_state(); if (!$c['cache']) return;    $k = $type . ':' . $ip; $now = time(); $c['cache']['writes']++;    if ($c['cache']['mode'] === 'sqlite' && ($pdo = pwhois_cache_pdo())) {        try { $pdo->prepare('INSERT INTO pwhois_cache (k, stored, used, rec) VALUES (:k, :t, :t, :r) ON CONFLICT(k) DO UPDATE SET stored = :t, used = :t, rec = :r')->execute([':k' => $k, ':t' => $now, ':r' => json_encode($rec)]); }        catch (Throwable $e) { }    } else {        $f = pwhois_cache_file($k); $tmp = $f . '.' . getmypid() . '.tmp';        if (@file_put_contents($tmp, json_encode(['r' => $rec])) !== false) @rename($tmp, $f); else @unlink($tmp);    }    if ($c['cache']['writes'] % 500 === 0) pwhois_cache_prune();}/* ---------------------------------------------------------------------------------   Allowance: what this process has spent today, and (from the service) what the   address you are querying from has left.   --------------------------------------------------------------------------------- *//** Queries this process has sent today (UTC), counted locally; cache hits are free. */function pwhois_usage(): int{    $c = &pwhois_state(); $day = gmdate('Y-m-d');    if (!is_array($c['usage']) || $c['usage']['day'] !== $day) $c['usage'] = ['day' => $day, 'n' => 0];    return (int) $c['usage']['n'];}function pwhois_usage_count(int $n): void { pwhois_usage(); $c = &pwhois_state(); $c['usage']['n'] += $n; }/** * Your daily allowance as the service sees it, for the address this call is made from: * ['address', 'limit', 'used', 'remaining', 'resets_at' (ISO 8601 UTC)]. Free; it is not a * whois query. Returns null when the service cannot be reached. */function pwhois_quota(array $options = []): ?array{    $url = (string) ($options['quota_url'] ?? 'https://pwhois.org/tools/quota.php');    $ctx = stream_context_create(['http' => ['method' => 'GET', 'timeout' => 10, 'header' => "User-Agent: " . PWHOIS_USER_AGENT . "\r\nAccept: application/json\r\n"]]);    $j = @file_get_contents($url, false, $ctx);    if ($j === false) return null;    $d = json_decode($j, true);    return (is_array($d) && isset($d['limit'])) ? $d : null;}/* ---------------------------------------------------------------------------------   Backward compatibility with the 2005 interface (doPWLookup / doPWLookupBulk).   Those returned keys with the hyphens removed ("originas") and 0 on failure; keep   that shape for existing callers. New code should use the pwhois_* functions.   --------------------------------------------------------------------------------- */if (!function_exists('doPWLookup')) {    function doPWLookup($query)    {        $r = pwhois_lookup((string) $query, ['app' => 'PWPHPLib']);        if ($r === null) return 0;        $out = []; foreach ($r as $k => $v) $out[str_replace('-', '', $k)] = (string) $v;        return $out;    }}if (!function_exists('doPWLookupBulk')) {    function doPWLookupBulk($queryarray)    {        $opts = ['app' => 'PWPHPLib'];        $r = pwhois_lookup_bulk(is_array($queryarray) ? $queryarray : [], $opts);        if ($r === null) return 0;        $out = [];        foreach ($r as $ip => $rec) { if ($rec === null) continue; $flat = []; foreach ($rec as $k => $v) $flat[str_replace('-', '', $k)] = (string) $v; $out[$ip] = $flat; }        return $out;    }}