You are viewing the website for BitFrame v1. BitFrame v2.0 was released on 11-May-2020 — new documentation and website will be available soon!


Plug & Play middleware, ready to integrate


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


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  */
$geoloc = new GeoLocation($remoteIpLookup);


Getting Started

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

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.

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:

← Install IP Lookup →

require 'vendor/autoload.php';

$app = new \BitFrame\Application;

$geoloc = new \BitFrame\Locale\GeoLocation;


$ip = $geoloc->getIpAddress($app->getRequest(), true);// defaults to:
$remoteLookupAddr = $geoloc->getRemoteAddr();/* Get client IP address  */
$ip = $geoloc->getIpAddress($app->getRequest());/* Changes proxy handling setting which determines whether to 
 * use proxy addresses or not  */
$geoloc->setUseProxy(true);// defaults to: false
$useProxy = $geoloc->isUseProxy();/* Set list of trusted proxy addresses  */
]);// defaults to: []
$trustedProxies = $geoloc->getTrustedProxies();/* Set the header to introspect for proxy IPs  */
]);/* defaults to:  */ 
$proxyHeader = $geoloc->getProxyHeader();

IP Lookup

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

  • setRemoteAddr($addr)
  • getRemoteAddr(): string
  • getIpAddress($request, $remoteLookup): string
  • 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  */
    new FreeGeoIp($client),
    new GeoPlugin($client)
]);/* defaults to:  */
$provider = $geoloc->getProvider();/* Get location data  */
$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;

    /* \BitFrame\Message\DiactorosResponseEmitter::class, */
    function($request, $response, $next) use ($geoloc) {
        $loc = $request->getAttribute(GeoLocationData::class);$geoloc->getGeoLocationData($request, '');$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

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

  1. By using the \BitFrame\Locale\GeoLocation middleware;
  2. 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.

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

/* \BitFrame\Locale\GeoLocationData([
    'geocoder', // \Geocoder\Location object
    '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    
 * @copyright Copyright (c) 2017-2018 Daniyal Hamid (
 * @license   MIT License


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

GeoCoder Official GitHub

← Geo Location Data API →


Let us know if you have something to say or add


Latest version 1.0.0 released on 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