PHPackages                             webiny/geoip - 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. [Utility & Helpers](/categories/utility)
4. /
5. webiny/geoip

ActiveLibrary[Utility & Helpers](/categories/utility)

webiny/geoip
============

Geo location component

0.1.x-dev(8y ago)086MITPHPPHP >=5.5.9

Since Sep 11Pushed 8y ago9 watchersCompare

[ Source](https://github.com/Webiny/GeoIp)[ Packagist](https://packagist.org/packages/webiny/geoip)[ Docs](http://www.webiny.com/)[ RSS](/packages/webiny-geoip/feed)WikiDiscussions master Synced today

READMEChangelogDependencies (4)Versions (2)Used By (0)

GeoIp
=====

[](#geoip)

GeoIp is a simple component providing location information for a given IPv4 or IPv6 address.

Example:

```
$geo = new \Webiny\GeoIp\GeoIp(new \Webiny\GeoIp\Provider\FreeGeoIp\FreeGeoIp());
$location = $geo->getGeoIpLocation('8.8.8.8');

// output
array(
   'continentCode' => NULL,
   'continentName' => NULL,
   'countryCode' => 'US',
   'countryName' => 'United States',
   'cityName' => 'Mountain View',
   'subdivision1Code' => 'CA',
   'subdivision1Name' => 'California',
   'subdivision2Code' => NULL,
   'subdivision2Name' => NULL,
   'timeZone' => 'America/Los_Angeles',
)
```

Depending on the provider, different information will be available. The GeoIp standard library comes with 2 providers:

- `FreeGeoIp`: uses the  API
- `MaxMindGeoLite2`: uses the GeoLite2 database provided by MaxMind (requires a Mongo database)

Install GeoIp
-------------

[](#install-geoip)

The best way to install the component is using Composer.

```
composer require webiny/geoip
```

For additional versions of the package, visit the [Packagist page](https://packagist.org/packages/webiny/geoip).

Setup
-----

[](#setup)

### FreeGeoIp

[](#freegeoip)

If you plan to use the `FreeGeoIp` API, no setup is required, just create a provider instance and pass it to the `GeoIp` class, like so:

```
$providerInstance = new \Webiny\GeoIp\Provider\FreeGeoIp\FreeGeoIp()

$geo = new \Webiny\GeoIp\GeoIp($providerInstance);
$location = $geo->getGeoIpLocation('8.8.8.8');
```

### MaxMindGeoLite2

[](#maxmindgeolite2)

This provider requires a Mongo database, that is configured using `Webiny\Mongo` component. In addition to the database, some other parameters are also required, so here is an example config:

```
MaxMind:
    GeoLite2Url: http://geolite.maxmind.com/download/geoip/database/GeoLite2-City-CSV.zip
    Language:  en
Entity:
    Database: GeoIp
Mongo:
    Services:
        GeoIp:
            Class: \Webiny\Component\Mongo\Mongo
            Arguments:
                Host: 127.0.0.1:27017
                Database: YourDatabase ## CHANGE THIS
                Username: null
                Password: null
                CollectionPrefix: ''
```

The `MaxMind` section defines the download location of the GeoLite2 database and the language for the location name that will be imported from that database. The `Entity` and `Mongo` section are standard configurations as described under `Webiny/Entity` and `Webiny/Mongo` components.

Once you have your configuration in place, run the following command in your terminal:

```
php /path/to/src/Webiny/GeoIp/Provider/MaxMindGeoLite2/run-installer.php abs-path-to-your-config-yaml-file
```

This will download the GeoLite2 database and setup the Mongo collections for you. Note that the process might take up to 15-30 min, depending on your hardware.

Once the installation finishes, you can use the provider like so:

```
$config = 'abs-path-to-your-config-yaml-file';
$provider = new Webiny\GeoIp\Provider\MaxMindGeoLite2\MaxMindGeoLite2($config);

$geo = new \Webiny\GeoIp\GeoIp($provider);
$location = $geo->getGeoIpLocation('8.8.8.8');
```

### Custom provider

[](#custom-provider)

If you wish to implement a custom provider, just create a class for your provider that implements `Webiny\GeoIp\ProviderInterface`;

Location class
--------------

[](#location-class)

The location class is the result of the geo ip lookup. Depending on the provider, the amount of information might vary. Overall, a typical lookup result looks like this:

```
Webiny/GeoIp/Location::__set_state(array(
   'continentCode' => 'NA',
   'continentName' => 'North America',
   'countryCode' => 'US',
   'countryName' => 'United States',
   'cityName' => 'Mountain View',
   'subdivision1Code' => 'CA',
   'subdivision1Name' => 'California',
   'subdivision2Code' => '',
   'subdivision2Name' => '',
   'timeZone' => 'America/Los_Angeles',
))
```

Note that if the location cannot be determined, `false` will be returned instead of the `Location` instance.

License and Contributions
-------------------------

[](#license-and-contributions)

Contributing > Feel free to send PRs.

License > [MIT](LICENSE)

Resources
---------

[](#resources)

To run unit tests, you need to use the following command:

```
$ cd path/to/GeoIp/
$ composer install
$ phpunit

```

###  Health Score

23

—

LowBetter than 26% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity9

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 72.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

3218d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/4440afa738ed146b05c06073a90345e0464c4f4d042b039532d881ca24859d77?d=identicon)[SvenAlHamad](/maintainers/SvenAlHamad)

---

Top Contributors

[![SvenAlHamad](https://avatars.githubusercontent.com/u/3808420?v=4)](https://github.com/SvenAlHamad "SvenAlHamad (8 commits)")[![Pavel910](https://avatars.githubusercontent.com/u/3920893?v=4)](https://github.com/Pavel910 "Pavel910 (2 commits)")[![adrians5j](https://avatars.githubusercontent.com/u/5121148?v=4)](https://github.com/adrians5j "adrians5j (1 commits)")

---

Tags

geoipgeo-location

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/webiny-geoip/health.svg)

```
[![Health](https://phpackages.com/badges/webiny-geoip/health.svg)](https://phpackages.com/packages/webiny-geoip)
```

###  Alternatives

[stevebauman/location

Retrieve a user's location by their IP Address

1.3k8.5M84](/packages/stevebauman-location)[torann/geoip

Support for multiple Geographical Location services.

2.2k14.9M92](/packages/torann-geoip)[willdurand/geocoder

Common files for PHP Geocoder

17437.9M168](/packages/willdurand-geocoder)[ipip/db

IPIP.net officially supported IP database ipdb format parsing library

137207.1k6](/packages/ipip-db)[adrianorosa/laravel-geolocation

Laravel Geo Location package to get details for a given IP Address

6598.6k1](/packages/adrianorosa-laravel-geolocation)[bobey/geoip2-geolite2-composer

This tiny repository aims to provide an easy solution to require GeoIP2 / GeoLite2 databases inside your project using composer.

17896.8k1](/packages/bobey-geoip2-geolite2-composer)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)