Download the PHP package germania-kg/ipstack without Composer

Germania KG · ipstack client

PHP client for the ipstack API with cache support and middleware

Installation

Using ipstack

Response example

The IpstackClient internally works with array and thus asks ipstack to return JSON. Here is a shortened example; For a full example see ipstack's documentation on Standard IP lookups:

Customizing the response

You can customize the ipstack response by adding certain fields to the underlying request, as explained in the ipstack docs on “Specify Response Fields”. Just pass an array with query fields which will be added to the GET request:

Caching the ipstack response

If you are using a ipstack free plan limited to with 10.000 requests a month, you may want to save requests by saving the lookup results to a PSR-6 Cache. The IpstackClientPsr6CacheDecorator implements the IpstackClientInterface as well and thus can transparently be used in place of the IpstackClient.

Its constructor accepts your IpstackClient instance and a PSR-6 CacheItemPool instance. This example uses the cache implementation from Stash:

Middleware

The IpstackMiddleware can be used as PSR-15 Middleware as well as a traditional Slim3-style “Double pass” middleware. It requires the IpstackClient instance and will inject a ipstack attribute to the Request object that carries the IpstackClient's response. This example shows the “Double pass” approach:

In your Controller, you then simply grab the ipsatck information from the Request object:

A word on IP addresses

The IP address used for the ipstack request is per default determined from $_SERVER['REMOTE_ADDR']. It is recommended to use Rob Allen aka akrabat's Client IP address middleware that determines the IP address more safely.

Pitfall 1: Akrabats middleware must be used BEFORE the IpstackMiddleware. It must be added second to the Slim app.

Pitfall 2: Akrabats middleware allows customizing the request attribute name for the client IP address. From the docs:

By default, the name of the attribute is 'ip_address'. This can be changed by the third constructor parameter.

This means, the IP may be stored in a custom request attribute. The IpstackMiddleware therefore must know this attribute name.

Simply pass the IP address attribute name as second constructor, be it default or custom. Remember, if you leave this parameter out, $_SERVER['REMOTE_ADDR'] will be used as fallback.

Exceptions

The IpstackClient checks for Guzzle Exceptions during request and evaluate ipstack error responses. Both will be abstracted to IpstackRequestException, or IpstackResponseException respectively, both of them implementing the IpstackExceptionInterface.

Development

Unit testing

Copy phpunit.xml.dist to phunit.xml and adapt the ipstack-related globals. Endpoint and API key are self-explaining; the dummy IP4 and IP6 are IP addresses to check during test runs. The IP examples used here are Google's DNS servers.

Run phpunit using vendor binary or composer test script: