dotkernel/dot-geoip

DotKernel component based on Maxmind's geoip2/geoip2 package, using their free GeoLite2 databases to provide geographical details about an IP address.

3.7.0 2024-04-11 09:46 UTC

Requires

• php: ~8.2.0 || ~8.3.0
• dotkernel/dot-cli: ^3.5
• geoip2/geoip2: ^3.0
• guzzlehttp/guzzle: ^7.8
• laminas/laminas-filter: ^2.34
• psr/container: ^1.1
• symfony/filesystem: ^7.0

Requires (Dev)

• laminas/laminas-coding-standard: ^2.5
• mikey179/vfsstream: ^1.6.7
• phpunit/phpunit: ^10.5
• vimeo/psalm: ^5.21

MIT

• DotKernel Team

• geoip
• dotkernel
• laminas
• mezzio

README

DotKernel component based on Maxmind's geoip2/geoip2 package, using db-ip.com's free GeoLite2 databases to provide geographical details about an IP address.

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 it's 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.

Tip: If you setup 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 of the above + estimated coordinates + timezone
            return $this->locationService->getLocation($ipAddress);
        } catch (Throwable $exception) {
            // handle errors
        }
    }
}