README

Shlink module with tools to geolocate a request 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 request locations

This module provides strategies to resolve the location of a request, all of them implementing Shlinkio\Shlink\IpGeolocation\Resolver\LocationResolverInterface.

This interface basically exposes this method:

/**
 * @throws LocationResolutionException
 */
public function resolveRequestLocation(ServerRequestInterface $request): Model\Location;

These are the strategies provided implementing this interface:

GeoLite2LocationResolver: It makes use of a GeoLite2 database to resolve the request's IP address location.
CloudflareLocationResolver: It makes use of headers provided by Claudflare when set in front of your service.
EmptyLocationResolver: This one is a dummy resolver which always returns an empty location as if it was not capable of resolving the location.
ChainLocationResolver: It wraps a list of resolvers and calls them sequentially until one of them is capable of resolving the location.

Configure geolocation strategies

The chain resolver encapsulates others in the order you configure, and is the one recommended to use. It always includes an EmptyLocationResolver at the end of the chain.

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

To configure which resolver strategies to use and their order, you need to define a configuration like this:

<?php
declare(strict_types=1);

use Shlinkio\Shlink\Geolocation\Resolver\GeolocationStrategy;

return [

    // The corresponding resolvers will be called in order, so you can define which one should go first
    'geolocation_resolvers' => [GeolocationStrategy::CLOUDFLARE, GeolocationStrategy::GEOLITE2],

];

GeoLite2

Handling GeoLite2 DB file

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

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

shlinkio / shlink-ip-geolocation

Package info

Security

Statistics