Download the PHP package skpassegna/ipregistry-php-sdk without Composer

1. Introduction

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:

• Complete API Coverage: Supports all Ipregistry API endpoints, including single and batch lookups for IPs and ASNs, origin lookups, and User-Agent parsing.
• JSON and XML Support: Handles responses in both JSON (default) and XML formats.
• Robust Error Handling: Throws specific exceptions for Ipregistry API error codes and network errors, aiding in debugging.
• Convenience Methods: Provides easy-to-use methods for accessing data fields from responses.
• Composer Integration: Installable and managed through Composer for easy dependency management.
• PSR-4 Autoloading: Adheres to PSR-4 autoloading standards for seamless integration into PHP projects.

2. Installation

The SDK is distributed as a Composer package. To install it, run the following command in your project's root directory:

3. Getting Started

3.1. Obtain an API Key:

Sign up for a free Ipregistry account at https://ipregistry.co to obtain your API key.

3.2. Configure the SDK:

4. Usage: Endpoints and Methods

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.

4.1. IP Address Lookup (IpLookup)

• Single IP Lookup:

• Batch IP Lookup:

• Origin IP Lookup:

4.2. ASN Lookup (ASNLookup)

• Single ASN Lookup:

• Batch ASN Lookup:

• Origin ASN Lookup:

4.3. User-Agent Parsing (UserAgentParsing)

• Single User-Agent Parsing:

• Batch User-Agent Parsing:

• Origin User-Agent Parsing:

5. Accessing Response Data

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.
    • Examples: getIp(), getCountryCode(), getTimeZoneId(), getUserAgentName().
  • is[FieldName](): Used for boolean fields, where [FieldName] is the CamelCase representation of the field name.
    • Examples: isInEu(), isVpn(), isTor().
  • raw(): Returns the raw Guzzle ResponseInterface object.

Example:

Refer to the Ipregistry\Sdk\Response class documentation for a complete list of available convenience methods.

6. Error Handling

The SDK uses a structured exception system to handle errors:

• Ipregistry\Sdk\Exception\IpregistryException: The base exception class for all SDK-specific errors.
• Specific Exception Classes: Subclasses of 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
• Guzzle Exceptions: Network-related exceptions from Guzzle (e.g., 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:

7. Configuration Options

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:

8. Testing (not completed)

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:

9. Contributing

Contributions to the Ipregistry PHP SDK are welcome! Please open an issue or submit a pull request on GitHub.

10. License

This SDK is licensed under the GPL-3.0-or-later License.