PHP library that determines the country of an IP address
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
.gitignore Update dependencies and documentation Oct 1, 2018
.travis.yml Initialize tests Nov 11, 2018
LICENSE Add Travis CI badge Nov 11, 2018
composer.json Initialize tests Nov 11, 2018
phpunit.xml Initialize tests Nov 11, 2018

PHP Geolocation

Build Status

This package provides a PHP library that determines the country of an IP address.


You can easily install PHP Geolocation with composer.

composer require divineomega/php-geolocation


The most simple usage of PHP Geolocation is to create a new Locator object and call its getCountryByIP method.

// Get country of the current request's IP address
$country = (new Locator)->getCountryByIP($_SERVER['REMOTE_ADDR']);

// Get country of a specific IP address
$country = (new Locator)->getCountryByIP('');

// Returns a Country object
object(DivineOmega\Countries\Country)#4693 (16) {
  string(13) "United States"
  string(24) "United States of America"
  // etc...


You can configure PHP Geolocation to use any PSR-6 compliant caching library. This is easily done using the setCache method.

The following example configures a file cache (provided by the cache/filesystem-adapter package).

use League\Flysystem\Adapter\Local;
use League\Flysystem\Filesystem;
use Cache\Adapter\Filesystem\FilesystemCachePool;

$filesystemAdapter = new Local(__DIR__.'/');
$filesystem = new Filesystem($filesystemAdapter);
$cachePool = new FilesystemCachePool($filesystem);

$locator = new Locator;

$country = $locator->getCountryByIP('');

Alternative location providers

By default, PHP Geolocation will try to use the operating system's native whois command to determine the IP address. If you wish you can use an alternative location provider. This can be done using the setLocationProvider method, as follows.

$locator = new Locator;
$locator->setLocationProvider(new IpStack('my_ip_stack_api_key');

$country = $locator->getCountryByIP('');

To get a free api key sign up at Ip Stack's website.

If you wish to develop your own location provider, simply create a new class that implements the LocationProviderInterface provided in this package. See the existing WhoIs and FreeGeoIP location provider classes if you need help creating your own location provider.