Geolocation Locale Middleware - BitFrame PHP Microframework

Geolocation

Plug & Play middleware, ready to integrate

{
    "require": {
		"designcise/bitframe-geolocation": "^1.0.0"
	}
}

Install

Add the following as a dependency in your project's composer.json:

"designcise/bitframe-geolocation": "^1.0.0"

Getting Started →

use \BitFrame\Locale\GeoLocation;

require 'vendor/autoload.php';

$app = new \BitFrame\Application;

// instantiation with default options
$geoloc = new GeoLocation;// lazy instantiation with default options
$geoloc = GeoLocation::class;/* instantiate with custom options 
 *
 * @param bool $remoteIpLookup
 */
$geoloc = new GeoLocation($remoteIpLookup);

$app->run([
    $geoloc
]);

Getting Started

Instantiate with Default Options

You can create a new instance of \BitFrame\Locale\GeoLocation simply by using the new keyword.

Lazy Instantiation with Default Options

You can also do lazy instantiation, if it's supported by your middleware dispatcher, by just providing the class name with its namespace, or simply by appending ::class to an object instance or class name.

Instantiate with Custom Options

You can specify the following argument when creating a new instance of the object:

remoteIpLookup (bool, optional): (default: false) If true, the ip address is looked up using a remote service (such as the default lookup service: https://api.ipify.org/?format=text).

← Install IP Lookup →

require 'vendor/autoload.php';

$app = new \BitFrame\Application;

$geoloc = new \BitFrame\Locale\GeoLocation;

$geoloc->setRemoteAddr('http://ipecho.net/plain');

$ip = $geoloc->getIpAddress($app->getRequest(), true);// defaults to: https://api.ipify.org/?format=text
$remoteLookupAddr = $geoloc->getRemoteAddr();/* Get client IP address  
 *
 * @param \Psr\Http\Message\ServerRequestInterface $request
 * @param bool $remoteLookup
 */
$ip = $geoloc->getIpAddress($app->getRequest());/* Changes proxy handling setting which determines whether to 
 * use proxy addresses or not  
 *
 * By default this setting is disabled - IP address is mostly needed to 
 * increase security. HTTP_* are not reliable since can easily be spoofed. 
 * Enabling this setting can provide more flexibility, but if user uses 
 * proxy to connect to trusted services it's their own risk; the only reliable  
 * field for IP address is $_SERVER['REMOTE_ADDR'].
 * 
 * @param bool $useProxy Check for proxied IP addresses?
 */
$geoloc->setUseProxy(true);// defaults to: false
$useProxy = $geoloc->isUseProxy();/* Set list of trusted proxy addresses  
 *
 * @param string[] $trustedProxies
 */
$geoloc->setTrustedProxies([
    '10.10.10.10', 
    '10.10.10.11'
]);// defaults to: []
$trustedProxies = $geoloc->getTrustedProxies();/* Set the header to introspect for proxy IPs  
 *
 * @param string[] $header
 */
$geoloc->setProxyHeader([
    'X-Forwarded',
    'X-Forwarded-For'
]);/* defaults to: [
 *     'Forwarded',
 *     'Forwarded-For',
 *     'X-Forwarded',
 *     'X-Forwarded-For',
 *     'X-Cluster-Client-Ip',
 *     'Client-Ip'
 * ];
 */ 
$proxyHeader = $geoloc->getProxyHeader();

IP Lookup

The following IP lookup methods are available on the \BitFrame\Locale\GeoLocation instance (via \BitFrame\Locale\RemoteAddressTrait):

Retrieving the IP Address

setRemoteAddr($addr)
getRemoteAddr(): string
getIpAddress($request, $remoteLookup): string

Proxy-related Settings

setUseProxy($useProxy)
isUseProxy(): bool
setTrustedProxies($trustedProxies)
getTrustedProxies(): array
setProxyHeader($header)
getProxyHeader(): array

← Getting Started Geo Location Lookup →

use \Http\Adapter\Guzzle6\Client;
use \Geocoder\Provider\FreeGeoIp\FreeGeoIp;
use \Geocoder\Provider\GeoPlugin\GeoPlugin;

use \Geocoder\Provider\Chain\Chain;
use \Geocoder\Provider\FreeGeoIp\FreeGeoIp;
use \Geocoder\Provider\GeoPlugin\GeoPlugin;

require 'vendor/autoload.php';

$app = new \BitFrame\Application;

$geoloc = new \BitFrame\Locale\GeoLocation;

$client = new Client();

/* Set Geocoder Provider 
 *
 * @param \Geocoder\Provider\Provider|array $provider
 *
 * @see https://github.com/geocoder-php/Geocoder#providers
 *
 * @throws \InvalidArgumentException
 */
$geoloc->setProvider([
    new FreeGeoIp($client),
    new GeoPlugin($client)
]);/* defaults to: 
 * new Chain([
 *     new FreeGeoIp($client),
 *     new GeoPlugin($client)
 * ]);
 */
$provider = $geoloc->getProvider();/* Get location data 
 *
 * @param \Psr\Http\Message\ServerRequestInterface $request
 * @param string $ip
 *
 * @return \Geocoder\Collection
 *
 * @throws \BitFrame\Locale\Exception\IpAddressNotFoundException
 * @throws \InvalidArgumentException
 */
$geodata = $geoloc->getGeoLocationData($request, $ip);

Geo Location Lookup

The following Geo Location lookup methods are available on the \BitFrame\Locale\GeoLocation instance (via \BitFrame\Locale\GeoLocationTrait):

setProvider($provider)
getProvider(): \Geocoder\Provider\Provider
getGeoLocationData($request, $ip): \Geocoder\Collection

← IP Lookup Geo Location Data →

use \BitFrame\Locale\GeoLocationData;

use \BitFrame\Locale\GeoLocationData;

require 'vendor/autoload.php';

$app = new \BitFrame\Application;

$geoloc = new \BitFrame\Locale\GeoLocation;

$app->run([
    /* In order to output the http response from the middlewares, 
     * make sure you include a response emitter middleware, for example:
     * \BitFrame\Message\DiactorosResponseEmitter::class, */
    $geoloc,$geoloc,
    function($request, $response, $next) use ($geoloc) {
        $loc = $request->getAttribute(GeoLocationData::class);$geoloc->getGeoLocationData($request, '8.8.8.8');$request->getAttribute(GeoLocationData::class);

        // e.g. United Kingdom (UK)
        $response->getBody()->write('<pre>' . print_r($loc, true) . '</pre>''<pre>' . print_r($loc, true) . '</pre>'"{$loc['country']} ({$loc['country_code']})");

        return $response;
    }
]);

Geo Location Data

Retrieving the Geo Location Data

There are two ways you can retrieve the geo location data:

By using the \BitFrame\Locale\GeoLocation middleware;
By calling the getGeoLocationData() method on a \BitFrame\Locale\GeoLocation object instance.

While the first method produces a \BitFrame\Locale\GeoLocationData object with important bits of location data (that is passed on to any subsequent middlewares), for the second method you'll have to work with the \Geocoder\Collection object (returned by the getGeoLocationData() method) and retrieve the data you need manually.

Using GeoLocationData Object

By default, the \BitFrame\Locale\GeoLocationData stores the following geo-location data:

/* \BitFrame\Locale\GeoLocationData([
    'ip',
    'geocoder', // \Geocoder\Location object
    'longitude',
    'latitude',
    'locality',
    'country',
    'country_code',
    'timezone',
    'date_checked' // ISO 8601 date
]); */

You can easily retrieve the data as you would with a normal array (as the class implements the \ArrayAccess interface).

The \BitFrame\Locale\GeoLocationData object is immutable which means you can't set or unset the data stored in it.

← Geo Location Lookup About →

/**
 * GeoCoder Wrapper & IP Lookup Service (PSR-15 / PSR-7 compatible)
 *
 * @author    Daniyal Hamid
 * @copyright Copyright (c) 2017-2018 Daniyal Hamid (https://designcise.com)
 *
 * @license   MIT License
 */

About

A BitFrame locale package that helps lookup client IP address along with geo location data.

GeoCoder Official GitHub

← Geo Location Data API →

Comments

Let us know if you have something to say or add

Changelog

Latest version 1.0.0 released on Feb 14, 2018

Feb 14, 2018

Version 1.0.0

IP Lookup & Geo Location Lookup can be used independently (as they're coded as traits)
PSR-15 & PSR-7 support
Support to specify remote ip lookup
Uses the GeoCoder PHP package for retrieving the Geo Location Data