PHPackages                             ayesh/geo-ip - 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. ayesh/geo-ip

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

ayesh/geo-ip
============

Fast IP to country lookup based on Maxmind Lite database, with no requirement for extension or binary database

v1.0.1(5y ago)4301[1 PRs](https://github.com/Ayesh/Geo-IP/pulls)MITPHPPHP ^7.4 || ^8.0

Since Jan 18Pushed 5y ago1 watchersCompare

[ Source](https://github.com/Ayesh/Geo-IP)[ Packagist](https://packagist.org/packages/ayesh/geo-ip)[ RSS](/packages/ayesh-geo-ip/feed)WikiDiscussions main Synced 4w ago

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

Geo IP
======

[](#geo-ip)

Fast IP address to country code lookup - Extension-less, automatic updates, and fast JSON tree lookup

Introduction
------------

[](#introduction)

A PHP package to lookup the country of a given IP address (IPv4 supported, IPv6 on the way).

This library focuses on performance and simplicity, at the cost of slightly less precision. It is designed to return an ISO country for a given IP address, and does it well. It does not provide precise locations (such as region or city) by design.

This library uses [Ayesh/Geo-IP-Database](https://github.com/Ayesh/Geo-IP-Database), an automated repository that publishes database updates weekly at most. The database is entirely a list of flag JSON files, that maps IP ranges to a country code.

This library does not require storing a binary data file, or HTTP requests, and thus is extremely fast.

> Note that the data may not be as accurate as a full database. Autofilling the country field in a form, or redirecting a user to a regional site are some of the ideal use case. Pinpointing the precise user location to find hot singles in the area is pushing it too much.

Automatic updates
-----------------

[](#automatic-updates)

This library depends on [Ayesh/Geo-IP-Database](https://github.com/Ayesh/Geo-IP-Database) package, that provides the JSON files list.

Automatic updates to the `ayesh/geo-ip-database` package means an update to the database. They are in the format of `v1.0.YYYYMMDD`.

Occassional `composer update` will automatically trigger database updates.

Installation
------------

[](#installation)

Install this library with the following command. Alternately, it is possible to manually edit the `composer.json` file and add `ayesh/geo-ip` package as well.

```
composer require ayesh/geo-ip
```

Usage
-----

[](#usage)

This library provides a `\Ayesh\GeoIP\GeoIPLookup` class. Use the Composer autoloader (highly recommended), or manually `require` `src/GeoIPLookup.php` file.

### Automatic database discovery

[](#automatic-database-discovery)

```
use Ayesh\GeoIP\GeoIPLookup;

$geoip = GeoIPLookup::createFromDefaultDatabase();
$geoip->lookup('8.8.8.8'); // "US"
$geoip->lookup('123.19.12.50'); // "VN"
```

The `createFromDefaultDatabase` static method creates a `GeoIPLookup` by setting the JSON data directory to the default `ayesh/geo-ip-database` location in a standard Composer installation (`vendor/ayesh/geo-ip-database/data`).

### Manual database path

[](#manual-database-path)

```
use Ayesh\GeoIP\GeoIPLookup;

$geoip = new GeoIPLookup('path/to/json/directory');
$geoip->lookup('8.8.8.8'); // "US"
$geoip->lookup('123.19.12.50'); // "VN"
```

Contributions and Issues
------------------------

[](#contributions-and-issues)

Feel free to open a PR or an issue for any contributions or support questions.

Database Source
---------------

[](#database-source)

This library makes use of `ayesh/geo-ip-database`, which in turn uses GeoLite2 data created by MaxMind, available from .

This library itself is MIT licensed. However, note that the MaxMind database is distributed under CC-BY-NC-SA-4.0.

###  Health Score

27

—

LowBetter than 49% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity14

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity57

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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

1936d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/1703f88c1f225e3fadff28458e81328f86668d9631a8c489f45ea1aaebe12df2?d=identicon)[Ayesh](/maintainers/Ayesh)

---

Top Contributors

[![Ayesh](https://avatars.githubusercontent.com/u/811553?v=4)](https://github.com/Ayesh "Ayesh (6 commits)")

### Embed Badge

![Health badge](/badges/ayesh-geo-ip/health.svg)

```
[![Health](https://phpackages.com/badges/ayesh-geo-ip/health.svg)](https://phpackages.com/packages/ayesh-geo-ip)
```

###  Alternatives

[symfony/polyfill-php72

Symfony polyfill backporting some PHP 7.2+ features to lower PHP versions

4.8k674.7M31](/packages/symfony-polyfill-php72)[symfony/polyfill-intl-icu

Symfony polyfill for intl's ICU-related data and classes

2.6k251.4M96](/packages/symfony-polyfill-intl-icu)[nette/php-generator

🐘 Nette PHP Generator: generates neat PHP code for you. Supports new PHP 8.5 features.

2.2k64.2M574](/packages/nette-php-generator)[consolidation/site-process

A thin wrapper around the Symfony Process Component that allows applications to use the Site Alias library to specify the target for a remote call.

5345.3M8](/packages/consolidation-site-process)[sycho/flarum-profile-cover

Adds the ability to add a cover image to a profile.

1836.6k](/packages/sycho-flarum-profile-cover)

PHPackages © 2026

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