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

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
        }
    }
}