Download the PHP package ipregistry/ipregistry-php without Composer

Ipregistry PHP Client Library

This is the official PHP client library for the Ipregistry IP geolocation and threat data API, allowing you to look up your own IP address or specified ones. Responses return multiple data points including carrier, company, currency, location, time zone, threat information, and more. The library can also parse raw User-Agent strings.

The library builds on the PHP standard library and the cURL extension, with PSR-16 (caching) and optional PSR-18 (HTTP client) interoperability.

Getting Started

You'll need an Ipregistry API key, which you can get along with 100,000 free lookups by signing up for a free account at https://ipregistry.co.

Installation

Requires PHP 8.2 or later with the curl and json extensions.

Quick start

Single IP lookup

Origin IP lookup

To look up the IP address the request is sent from — no argument needed — use lookupOrigin(). It returns a RequesterIpInfo, which additionally carries parsed User-Agent data:

Batch IP lookup

lookupBatch() resolves many IP addresses in a single request. Each entry may independently succeed or fail (for example on an invalid address), so results are inspected element by element. Iterate the list, or index into it with at(), which returns the data or throws the entry's error:

The Ipregistry API accepts up to 1024 IP addresses per request. lookupBatch() transparently splits larger arrays into several requests and reassembles the results in input order — so you can pass an arbitrarily long array without hitting TOO_MANY_IPS. Tune the chunk size when needed:

Only cache misses are sent to the API; if a whole sub-request fails (network or API error), lookupBatch() throws, whereas an individual bad address surfaces as a per-entry error as shown above.

Lookup options

Lookups accept named arguments that map to Ipregistry query parameters:

Caching

The client accepts any PSR-16 cache. Caching is disabled by default to ensure data freshness.

The library ships with an in-process InMemoryCache (LRU eviction plus TTL), which is a good fit for long-running processes such as queue workers or Swoole/FrankenPHP/RoadRunner servers:

In classic per-request PHP-FPM deployments, plug in a shared PSR-16 cache instead (APCu, Redis, Memcached, ...), for example with symfony/cache:

Origin (requester) lookups are never cached, because the requester IP is only known from the response. Batch lookups transparently serve already-cached entries and only request the remainder from the API.

Retries

Failed requests are automatically retried with an exponential backoff. By default, up to 3 retries are performed on transient network errors and 5xx server responses.

Because Ipregistry does not rate limit by default (rate limiting is opt-in per API key), retries on 429 Too Many Requests responses are disabled by default. Enable them if your API key is configured with a rate limit and you want the client to wait and retry (honoring the Retry-After header when present):

Timeouts and custom HTTP transports

By default the client sends requests through the cURL extension with a 15-second timeout:

For full control over connection pooling, proxying, TLS, or instrumentation, route requests through any PSR-18 HTTP client:

When you supply a PSR-18 transport, you own the HTTP client's configuration: the timeout argument is ignored in favor of your client's own settings. You can also implement Ipregistry\Http\TransportInterface directly.

Errors

The library throws two exception kinds, both extending Ipregistry\Exception\IpregistryException:

• ApiException — the API reported a failure (e.g. insufficient credits, throttling, invalid input). It carries the raw code (rawCode), a typed errorCode enum (null when the raw code is not recognized), a resolution, and the HTTP status.
• ClientException — a client-side failure (network error, invalid argument, response decoding). The underlying cause is available via getPrevious().

The full list of error codes is documented at ipregistry.co/docs/errors.

Parsing User-Agents

Parse one or more raw User-Agent strings (such as the User-Agent header of an incoming request) into structured data:

Filtering bots

You might want to prevent Ipregistry API calls for crawlers or bots browsing your pages. To help identify bots from the User-Agent, the library includes a lightweight helper:

Examples

Runnable examples live in the examples/ directory. Set your key and run one:

Testing

The library ships with two tiers of tests:

• Unit / behavior tests run offline — partly against PHP's built-in development server — so no API key or network is required. This is the default vendor/bin/phpunit run and what CI executes on every push.
• System tests exercise the live Ipregistry API. They live in their own PHPUnit test suite and are skipped unless IPREGISTRY_API_KEY is set (each successful lookup consumes credits):

Common tasks are wired through the Makefile: make test, make cover, make stan, make cs, make system, and make all.

Other Libraries

There are official Ipregistry client libraries available for many languages including Java, Javascript, Python, Go and more.

Are you looking for an official client with a programming language or framework we do not support yet? Let us know.

License

This library is released under the Apache 2.0 license.