ipscope / ipscope-php
Official zero-dependency, memory-safe PHP 8.2+ Server-Side SDK for the IPScope IP Intelligence Platform (hardened against CVE-2026-109618 / CVE-2026-109619).
Requires
- php: >=8.2.0
- ext-curl: *
- ext-json: *
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
ipscope/ipscope-php
Official zero-dependency, memory-safe PHP 8.2+ server SDK for ipscope — IP geolocation, BGP ASN, and VPN/proxy detection
What is this
ipscope/ipscope-php is the official, zero-external-dependency, memory-safe PHP 8.2+ server SDK for ipscope. Built strictly on ext-curl and ext-json, it queries the ipscope REST API for physical and declared IP geolocation, BGP origin ASN and prefix routing, and VPN, residential proxy, Tor exit, and relay detection.
Every IpScopeClient includes a bounded O(1) LRU + TTL cache (maxEntries: 512 default, < 400 KB memory footprint), a streaming CURLOPT_WRITEFUNCTION 2 MiB ceiling, bounded JSON recursion depth (16), and pre-OOM heap headroom guards designed specifically for persistent workers (PHP-FPM, FrankenPHP, RoadRunner, Swoole, Laravel Octane). For offline in-process lookups in PHP, see our downloadable MMDB databases.
Getting started
1. Get an API key
Create a free account at dashboard.ipscope.io and copy your server API key (<public>:<private>).
2. Install the package
composer require ipscope/ipscope-php
Or include the standalone autoloader directly:
require_once '/path/to/sdks/php/autoload.php';
3. Look up an IP address
<?php declare(strict_types=1); use IpScope\Sdk\IpScopeClient; $client = new IpScopeClient(apiKey: getenv('IPSCOPE_API_KEY') ?: '<public>:<private>'); $info = $client->lookupIp('8.8.8.8'); echo $info->ip . ' ' . $info->geo->countryCode . ' AS' . $info->network->asn . ' ' . $info->network->organization . PHP_EOL;
Contents
- Lookups
- Streaming large IP lists
- Network CIDR prefix lookups
- Rate-limit metadata
- Submitting feedback
- Memory & worker hardening
- Requirements
- Documentation
- Help
- Licence
Lookups
<?php declare(strict_types=1); use IpScope\Sdk\IpScopeClient; $client = new IpScopeClient(apiKey: '<public>:<private>'); // 1. Single IPv4 or IPv6 lookup (cached in bounded LRU) $ipInfo = $client->lookupIp('8.8.8.8'); echo $ipInfo->ip . ' IPv' . $ipInfo->ipVersion . ' ' . $ipInfo->geo->countryCode . ' AS' . $ipInfo->network->asn . ' ' . $ipInfo->network->organization . PHP_EOL; // Security booleans are true, false, or null (null = not enough evidence) echo 'VPN: ' . var_export($ipInfo->security->isVpn, true) . ' Hosting: ' . var_export($ipInfo->security->isHosting, true) . ' Tor exit: ' . var_export($ipInfo->security->isTorExit, true) . ' Anonymizer: ' . $ipInfo->security->anonymizerType . PHP_EOL; // 2. Caller IP lookup (GET /v1/ip/me) $me = $client->lookupCallerIp(); // 3. Batch lookup (up to 100 IPs; deduplicates & reuses cached entries automatically) $batch = $client->lookupBatch(['8.8.8.8', '1.1.1.1', '2606:4700:4700::1111']); foreach ($batch->results as $record) { echo $record->ip . ' -> ' . $record->network->organization . PHP_EOL; }
Streaming large IP lists
Enrich 10,000+ IP addresses with < 400 KB steady-state memory overhead using lookupBatchStream:
foreach ($client->lookupBatchStream($largeIpList) as $chunk) { foreach ($chunk->results as $record) { echo $record->ip . ' ' . $record->geo->countryCode . PHP_EOL; } }
Network CIDR prefix lookups
Inspect the longest-matching routed BGP prefix and its base address intelligence via lookupNetwork:
$prefix = $client->lookupNetwork('8.8.8.0/24'); echo $prefix->queriedCidr . ' matched ' . $prefix->matchedNetwork . ' org: ' . ($prefix->record?->organization ?? 'n/a') . PHP_EOL;
Rate-limit metadata
Inspect the parsed X-RateLimit-* headers from the last request or inspect service health and dataset versions:
$limits = $client->getLastRateLimit(); echo $limits?->remaining . '/' . $limits?->limit . ', resets in ' . $limits?->resetAfterSeconds . 's' . PHP_EOL; echo $client->getStatus()->currentVersion() . PHP_EOL; echo $client->getDatasetsMetadata()->activeVersion . PHP_EOL;
Submitting feedback
Report outdated geolocation or anonymity classifications directly via submitFeedback:
use IpScope\Sdk\FeedbackSubmissionInput; $client->submitFeedback(new FeedbackSubmissionInput( prefixOrIp: '8.8.8.0/24', role: 'network_owner', // network_owner | user | researcher issueType: 'wrong_city', // see FeedbackSubmissionInput::ISSUE_TYPES requestedCorrection: ['city' => 'Mountain View'], evidenceUrl: 'https://example.net/geofeed.csv', ));
Memory & worker hardening
ipscope/ipscope-php is hardened against PHP memory-limit bailout and persistent-worker state retention vulnerabilities (CVE-2026-109618 / CVE-2026-109619):
- Pre-OOM Heap Headroom Guard (
IpScopeSecurity::assertMemoryHeadroom): Before buffering HTTP chunks, decoding JSON, or inserting into the cache, the SDK checksmemory_get_usage(true)againstini_get('memory_limit'). If free heap headroom drops below8 MiB(DEFAULT_MIN_FREE_BYTES), the SDK throws a catchableIpScopeMemoryLimitExceptionbefore Zend Engine ever hitsmemory_limitand callszend_bailout(). - Streaming cURL Write Callback (
CURLOPT_WRITEFUNCTION): Inspects chunks on arrival and aborts transfers exceeding2 MiB(MAX_RESPONSE_BYTES). - Zero Static / Global State: Uses zero mutable static properties or
$GLOBALS, and$client->close()resets all internal buffers and caches between worker requests.
Requirements
- PHP 8.2 or later (
>=8.2.35,>=8.3.36,>=8.4.27, or>=8.5.12recommended) ext-curlandext-json
Documentation
| Topic | Link |
|---|---|
| PHP SDK guide | ipscope.io/docs/sdks/php |
| REST API overview | ipscope.io/docs/api/overview |
| Single & batch IP lookups | ipscope.io/docs/api/single-ip |
| Network CIDR prefix lookups | ipscope.io/docs/api/network-prefix |
| Errors & rate limits | ipscope.io/docs/api/errors |
| Downloadable MMDB databases | ipscope.io/docs/databases/mmdb |
Help
- Bugs and feature requests: open an issue
- Account, billing and integration questions: contact@ipscope.io
- Security vulnerabilities: see the security policy