IpRegistry PHP SDK (PSR-4 autoloading compatible/Unofficial)
GPL-3.0 License
The Ipregistry PHP SDK is an unofficial library that simplifies interaction with the Ipregistry API, enabling developers to easily access geolocation and threat data for IP addresses and Autonomous Systems (ASNs) within their PHP applications.
Key Features:
The SDK is distributed as a Composer package. To install it, run the following command in your project's root directory:
composer require skpassegna/ipregistry-php-sdk
Sign up for a free Ipregistry account at https://ipregistry.co to obtain your API key.
use Ipregistry\Sdk\IpRegistryClient;
use Ipregistry\Sdk\Config;
// Replace 'YOUR_API_KEY' with your actual Ipregistry API key.
$config = new Config('YOUR_API_KEY');
// (Optional) Customize base URL, timeout, hostname lookup, and output format:
// $config = new Config(
// 'YOUR_API_KEY',
// Ipregistry\Sdk\Constants::EU_BASE_URL, // Use EU base URL
// 10, // Set timeout to 10 seconds
// true, // Enable hostname lookup
// 'xml' // Set output format to XML
// );
$client = new IpRegistryClient($config);
The SDK provides separate classes for each API endpoint group:
Ipregistry\Sdk\Endpoint\IpLookup
: Handles IP address lookups.Ipregistry\Sdk\Endpoint\ASNLookup
: Handles ASN lookups.Ipregistry\Sdk\Endpoint\UserAgentParsing
: Handles User-Agent parsing.IpLookup
)Single IP Lookup:
$ipLookup = new IpLookup($client);
$response = $ipLookup->lookup('8.8.8.8');
echo "IP Address: " . $response->getIp() . PHP_EOL;
echo "Country: " . $response->getCountryName() . PHP_EOL;
echo "City: " . $response->getCity() . PHP_EOL;
// ... Access other IP-related data fields
Batch IP Lookup:
$ips = ['8.8.8.8', '1.1.1.1', '2001:4860:4860::8888'];
$batchResponse = $ipLookup->batchLookup($ips);
foreach ($batchResponse->getData()['results'] as $result) {
echo "IP: " . $result['ip'] . ", Country: " . $result['location']['country']['name'] . PHP_EOL;
}
Origin IP Lookup:
$originResponse = $ipLookup->originLookup();
echo "Originating IP: " . $originResponse->getIp() . PHP_EOL;
ASNLookup
)Single ASN Lookup:
$asnLookup = new ASNLookup($client);
$response = $asnLookup->lookup(15169);
echo "ASN Name: " . $response->getAsnName() . PHP_EOL;
// ... Access other ASN-related data fields
Batch ASN Lookup:
$asns = [15169, 20940];
$batchResponse = $asnLookup->batchLookup($asns);
foreach ($batchResponse->getData()['results'] as $result) {
echo "ASN: " . $result['asn'] . ", Name: " . $result['name'] . PHP_EOL;
}
Origin ASN Lookup:
$originResponse = $asnLookup->originLookup();
echo "Originating ASN: " . $originResponse->getAsn() . PHP_EOL;
UserAgentParsing
)Single User-Agent Parsing:
$userAgentParsing = new UserAgentParsing($client);
$response = $userAgentParsing->parse('Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36');
echo "Browser: " . $response->getUserAgentName() . PHP_EOL;
echo "Operating System: " . $response->getOsName() . PHP_EOL;
// ... Access other User-Agent related data fields
Batch User-Agent Parsing:
$userAgents = [
'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36',
'Mozilla/5.0 (iPhone; CPU iPhone OS 10_3_1 like Mac OS X) AppleWebKit/603.1.30 (KHTML, like Gecko) Version/10.0 Mobile/14E304 Safari/602.1'
];
$batchResponse = $userAgentParsing->batchParse($userAgents);
foreach ($batchResponse->getData()['results'] as $result) {
echo "User-Agent: " . $result['user_agent']['header'] . ", Browser: " . $result['user_agent']['name'] . PHP_EOL;
}
Origin User-Agent Parsing:
$originResponse = $userAgentParsing->originParse();
echo "Originating User-Agent: " . $originResponse->getUserAgentHeader() . PHP_EOL;
The Ipregistry\Sdk\Response
class handles API responses and provides methods for accessing data:
getData()
: Returns the parsed response data as an array (for JSON) or an object (for XML).
getRawResponse()
: Returns the raw Guzzle ResponseInterface
object.
Convenience Methods (Getters): The Response
class provides a comprehensive set of convenience methods (getters) for accessing specific data fields from the API responses. These methods follow a consistent naming convention:
get[FieldName]()
: Used for most fields, where [FieldName]
is the CamelCase representation of the field name in the API response.
getIp()
, getCountryCode()
, getTimeZoneId()
, getUserAgentName()
.is[FieldName]()
: Used for boolean fields, where [FieldName]
is the CamelCase representation of the field name.
isInEu()
, isVpn()
, isTor()
.raw()
: Returns the raw Guzzle ResponseInterface
object.Example:
$response = $ipLookup->lookup('8.8.8.8');
// Access data using getData()
$data = $response->getData();
echo "Country Code: " . $data['location']['country']['code'] . PHP_EOL; // Assuming JSON format
// Access data using convenience methods
echo "Country Name: " . $response->getCountryName() . PHP_EOL;
echo "Is in EU: " . ($response->isInEu() ? 'Yes' : 'No') . PHP_EOL;
Refer to the Ipregistry\Sdk\Response
class documentation for a complete list of available convenience methods.
The SDK uses a structured exception system to handle errors:
Ipregistry\Sdk\Exception\IpregistryException
: The base exception class for all SDK-specific errors.IpregistryException
are thrown for specific Ipregistry API error codes. These include:
InvalidApiKeyException
InsufficientCreditsException
BadRequestException
ForbiddenIpException
ForbiddenOriginException
ForbiddenIpOriginException
InvalidAsnException
InvalidIpAddressException
MissingApiKeyException
ReservedAsnException
ReservedIpAddressException
TooManyAsnsException
TooManyIpsException
TooManyRequestsException
TooManyUserAgentsException
UnknownAsnException
ConnectException
, RequestException
) are thrown for connectivity issues or request failures.Exception Properties:
$errorCode
: The Ipregistry API error code (if available).$resolution
: A suggestion from the Ipregistry API on how to resolve the error (if available).Example Error Handling:
try {
$response = $ipLookup->lookup('invalid-ip');
} catch (Ipregistry\Sdk\Exception\InvalidIpAddressException $e) {
echo "Error: " . $e->getMessage() . PHP_EOL;
echo "Error Code: " . $e->getErrorCode() . PHP_EOL;
echo "Resolution: " . $e->getResolution() . PHP_EOL;
} catch (Exception $e) {
// Handle other exceptions.
}
The SDK's behavior can be customized using the Ipregistry\Sdk\Config
class:
apiKey
(required): Your Ipregistry API key.baseUrl
(optional): The Ipregistry API base URL. Defaults to https://api.ipregistry.co
. You can use constants from Ipregistry\Sdk\Constants
to set regional base URLs (e.g., Constants::EU_BASE_URL
).timeout
(optional): Request timeout in seconds. Defaults to 5.hostname
(optional): Enable hostname lookup for IP address lookups. Defaults to false
.format
(optional): The desired output format. Accepts 'json'
(default) or 'xml'
.Example Configuration:
$config = new Config(
'YOUR_API_KEY',
Ipregistry\Sdk\Constants::EU_BASE_URL, // Use EU base URL
10, // Set timeout to 10 seconds
true, // Enable hostname lookup
'xml' // Set output format to XML
);
The SDK includes a comprehensive suite of unit tests using PHPUnit to ensure its reliability and correctness. The tests cover all endpoints, methods, and error scenarios.
Running Tests:
From the project's root directory, run:
./vendor/bin/phpunit
Contributions to the Ipregistry PHP SDK are welcome! Please open an issue or submit a pull request on GitHub.
This SDK is licensed under the GPL-3.0-or-later License.