README

Dotkernel component to provide geographical details about an IP address

dot-geoip is a wrapper on top of maxmind/GeoIP2-php

Documentation

Documentation is available at: https://docs.dotkernel.org/dot-geoip/.

Badges

👁 OSS Lifecycle
👁 PHP from Packagist (specify version)

👁 GitHub issues
👁 GitHub forks
👁 GitHub stars
👁 GitHub license

👁 Build Static
👁 codecov
👁 PHPStan

Install

You can install this library by running the following command:

composer require dotkernel/dot-geoip

If your application didn't already use it, the above command also installed dotkernel/dot-cli. In this case, see its README file on how to use it.

Copy config file vendor/dotkernel/dot-geoip/config/autoload/geoip.global.php into your application's config/autoload directory.

Register the library's ConfigProvider by adding the following line to your application's config/config.php file:

Dot\GeoIP\ConfigProvider::class,

Register the library's synchronizer command by adding the following line to your application's config/autoload/cli.global.php file under the commands array key:

Dot\GeoIP\Command\GeoIpCommand::getDefaultName() => Dot\GeoIP\Command\GeoIpCommand::class,

Manage GeoLite2 database

You can download/update a specific GeoLite2 database by running the following command:

php ./bin/cli.php geoip:synchronize -d {DATABASE}

Where {DATABASE} takes one of the following values: asn, city, country.

You can download/update all GeoLite2 databases at once by running the following command:

php ./bin/cli.php geoip:synchronize

The output should be similar to the below, displaying per row: database identifier: previous build datetime -> current build datetime.

asn: n/a -> 2021-07-01 02:09:34
city: n/a -> 2021-07-01 02:09:20
country: n/a -> 2021-07-01 02:05:12

Get help for this command by running php ./bin/cli.php help geoip:synchronize.

If you set up the synchronizer command as a cronjob, you can add the -q|--quiet option, and it will output data only if an error has occurred.

Usage

Below is an example implementation of using DotGeoip to retrieve information about an IP address.

<?php

declare(strict_types=1);

namespace Api\Example\Service;

use Dot\GeoIP\Service\LocationServiceInterface;
use Throwable;

/**
 * Class ExampleService
 * @package Api\Example\Service
 */
class ExampleService
{
 protected LocationServiceInterface $locationService;

 /**
 * ExampleService constructor.
 * @param LocationServiceInterface $locationService
 */
 public function __construct(LocationServiceInterface $locationService)
 {
 $this->locationService = $locationService;
 }

 /**
 * @param string $ipAddress
 * @return object
 */
 public function myMethod(string $ipAddress): object
 {
 try {
 // You can use any of the below methods:
 
 // Get CountryData, which includes isEuMember, isoCode and name
 return $this->locationService->getCountry($ipAddress);
 
 // Get ContinentData, which includes code and name
 return $this->locationService->getContinent($ipAddress);
 
 // Get OrganizationData, which includes asn and name
 return $this->locationService->getOrganization($ipAddress);

 // Get LocationData, which includes all the above + estimated coordinates and timezone
 return $this->locationService->getLocation($ipAddress);
 } catch (Throwable $exception) {
 // handle errors
 }
 }
}