PHPackages                             shlinkio/shlink-ip-geolocation - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. shlinkio/shlink-ip-geolocation

ActiveLibrary

shlinkio/shlink-ip-geolocation
==============================

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

v5.0.0(3mo ago)763.5k↓19.4%31MITPHPPHP ^8.4CI passing

Since Aug 12Pushed 3mo ago2 watchersCompare

[ Source](https://github.com/shlinkio/shlink-ip-geolocation)[ Packagist](https://packagist.org/packages/shlinkio/shlink-ip-geolocation)[ Docs](https://shlink.io)[ RSS](/packages/shlinkio-shlink-ip-geolocation/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (11)Versions (27)Used By (1)

Shlink IP Address Geolocation module
====================================

[](#shlink-ip-address-geolocation-module)

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

Most of the elements it provides require a [PSR-11](https://www.php-fig.org/psr/psr-11/) container, and it's easy to integrate on [mezzio](https://github.com/mezzio/mezzio) applications thanks to the `ConfigProvider` it includes.

[![Build Status](https://camo.githubusercontent.com/2ffc2b81825a4347699a50d3d66737bba7862f7e81be4b24eeb1dbc84796d197/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f73686c696e6b696f2f73686c696e6b2d69702d67656f6c6f636174696f6e2f63692e796d6c3f6272616e63683d6d61696e266c6f676f3d676974687562267374796c653d666c61742d737175617265)](https://github.com/shlinkio/shlink-ip-geolocation/actions/workflows/ci.yml?query=workflow%3A%22Continuous+integration%22)[![Code Coverage](https://camo.githubusercontent.com/078d0117d87b94fb721fdc974158e0413a4c42157908acaf532a165a719be812/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f67682f73686c696e6b696f2f73686c696e6b2d69702d67656f6c6f636174696f6e2f6d61696e3f7374796c653d666c61742d737175617265)](https://app.codecov.io/gh/shlinkio/shlink-ip-geolocation)[![Latest Stable Version](https://camo.githubusercontent.com/31f9489c025564eb437ead9ebdd3fc89777c11f912fb17424ac98e922ce28090/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f72656c656173652f73686c696e6b696f2f73686c696e6b2d69702d67656f6c6f636174696f6e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/shlinkio/shlink-ip-geolocation)[![License](https://camo.githubusercontent.com/98e1afe161c5d21e550e4b2de20ec42dde84e0e33d07f5313c87723251dabfd7/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f73686c696e6b696f2f73686c696e6b2d69702d67656f6c6f636174696f6e2e7376673f7374796c653d666c61742d737175617265)](https://github.com/shlinkio/shlink-ip-geolocation/blob/main/LICENSE)[![Paypal donate](https://camo.githubusercontent.com/f7bd7ab1d7bea7a4ac78f5189c56ce2dbf8cc73608863e0dd9408e10ddca4673/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f446f6e6174652d70617970616c2d626c75652e7376673f7374796c653d666c61742d737175617265266c6f676f3d70617970616c26636f6c6f72413d616161616161)](https://slnk.to/donate)

Install
-------

[](#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
----------------------

[](#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](https://dev.maxmind.com/geoip/geoip2/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
-------------------------

[](#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
---------------

[](#geolite2-config)

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

```