shlinkio/shlink-ip-geolocation

Shlink module with tools to geolocate an IP address using different strategies.

v4.0.0 2024-03-09 08:19 UTC

Requires

• php: ^8.2
• fig/http-message-util: ^1.1
• geoip2/geoip2: ^3.0
• guzzlehttp/guzzle: ^7.8
• shlinkio/shlink-config: ^3.0 || ^2.5
• symfony/filesystem: ^7.0 || ^6.4

Requires (Dev)

• devster/ubench: ^2.1
• phpstan/phpstan: ^1.10
• phpstan/phpstan-phpunit: ^1.3
• phpunit/phpunit: ^11.0
• roave/security-advisories: dev-master
• shlinkio/php-coding-standard: ~2.3.0
• symfony/var-dumper: ^7.0 || ^6.4

MIT

• Alejandro Celaya Alastrué

README

Shlink module with tools to geolocate an IP address using different strategies.

Most of the elements it provides require a PSR-11 container, and it's easy to integrate on mezzio applications thanks to the ConfigProvider it includes.

Install

Install this library using composer:

composer require shlinkio/shlink-ip-geolocation

This library is also an expressive module which provides its own ConfigProvider. Add it to your configuration to get everything automatically set up.

Resolving IP locations

This module provides a few different ways to resolve the location of an IP address, all of them implementing Shlinkio\Shlink\IpGeolocation\Resolver\IpLocationResolverInterface.

This interface basically exposes this method:

/**
 * @throws WrongIpException
 */
public function resolveIpLocation(string $ipAddress): Model\Location;

These are the strategies provided implementing this interface:

• GeoLite2LocationResolver: It makes use of a GeoLite2 database to resolve IP address locations.
• EmptyIpLocationResolver: This one is a dummy resolver which always returns an empty location as if it was not capable of resolving the address location.
• CainIpLocationResolver: It wraps a list of IP resolvers and calls them sequentially until one of them is capable of resolving the address location.

The first one is the most reliable, but requires an up-to-date GeoLite2 database (which handling is explained in next section).

However, the chain resolver encapsulates the other two in the order they are listed here, and is the one recommended to use.

It is aliased to the service with name Shlinkio\Shlink\IpGeolocation\Resolver\IpLocationResolverInterface.

Handling GeoLite2 DB file

In order to resolve IP address locations with the GeoLite2LocationResolver, an up-to-date local GeoLite2 database file.

To ease the management of this file, a Shlinkio\Shlink\IpGeolocation\GeoLite2\DbUpdater service is provided.

It exposes two public methods:

public function databaseFileExists(): bool;

/**
 * @throws RuntimeException
 */
public function downloadFreshCopy(?callable $handleProgress = null): void;

• databaseFileExists: Just tells if the database file exists already (either in an outdated or up to date form).
• downloadFreshCopy: Forces a new copy of the GeoLite2 database to be downloaded from MaxMind repos. It allows to optionally handle the progress of the download.

GeoLite2 config

To get both the resolver and the database updater to work, this configuration has to be defined:

<?php
declare(strict_types=1);

return [

    'geolite2' => [
        // Mandatory options
        'db_location' => __DIR__ . '/../../data/GeoLite2-City.mmdb',
        'temp_dir' => sys_get_temp_dir(),

        // Optional options
        'license_key' => 'kjhk45hkj34fdwe5', // If not set, no attempts to download the file will happen
    ],

];

• db_location: Tells where in the local filesystem the database file is located (or should be located once the DbUpdater downloads it).
• temp_dir: A temporary location where new versions of the database are located while downloading. Once a download succeeds, the new DB will be moved to the location defined in previous config option.
• license_key: The GeoLite license key used to download the database. Know how to generate your own.

This project includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com