PHPackages                             jord-jd/php-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. [Utility & Helpers](/categories/utility)
4. /
5. jord-jd/php-geolocation

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

jord-jd/php-geolocation
=======================

PHP library that determines the country of an IP address

v5.0.0(3mo ago)844[1 issues](https://github.com/Jord-JD/php-geolocation/issues)2LGPL-3.0-onlyPHPPHP ^8.1

Since Sep 22Pushed 3mo ago2 watchersCompare

[ Source](https://github.com/Jord-JD/php-geolocation)[ Packagist](https://packagist.org/packages/jord-jd/php-geolocation)[ GitHub Sponsors](https://github.com/DivineOmega)[ RSS](/packages/jord-jd-php-geolocation/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (5)Versions (15)Used By (2)

PHP Geolocation
===============

[](#php-geolocation)

[![CI](https://github.com/Jord-JD/php-geolocation/actions/workflows/ci.yml/badge.svg)](https://github.com/Jord-JD/php-geolocation/actions/workflows/ci.yml/badge.svg)

This package provides a PHP library that determines the country of an IP address.

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

[](#installation)

You can easily install PHP Geolocation with composer.

```
composer require jord-jd/php-geolocation

```

Usage
-----

[](#usage)

The most simple usage of PHP Geolocation is to create a new Locator object and call its `getCountryByIP` method.

```
// Get country of the current request's IP address
$country = (new Locator)->getCountryByIP($_SERVER['REMOTE_ADDR']);

// Get country of a specific IP address
$country = (new Locator)->getCountryByIP('93.184.216.34');

// Returns a Country object
/*
object(JordJD\Countries\Country)#4693 (16) {
  ["name"]=>
  string(13) "United States"
  ["officialName"]=>
  string(24) "United States of America"
  // etc...
}
*/
```

### Caching

[](#caching)

You can configure PHP Geolocation to use any PSR-6 compliant caching library. This is easily done using the `setCache` method.

The following example configures a file cache (provided by the `cache/filesystem-adapter` package).

```
use League\Flysystem\Adapter\Local;
use League\Flysystem\Filesystem;
use Cache\Adapter\Filesystem\FilesystemCachePool;

$filesystemAdapter = new Local(__DIR__.'/');
$filesystem = new Filesystem($filesystemAdapter);
$cachePool = new FilesystemCachePool($filesystem);

$locator = new Locator;
$locator->setCache($cachePool);

$country = $locator->getCountryByIP('93.184.216.34');
```

### Alternative location providers

[](#alternative-location-providers)

By default, PHP Geolocation will try to use the operating system's native `whois` command to determine the IP address. If you wish you can use an alternative location provider. This can be done using the `setLocationProvider` method, as follows.

```
$locator = new Locator;
$locator->setLocationProvider(new IpStack('my_ip_stack_api_key');

$country = $locator->getCountryByIP('93.184.216.34');
```

*To get a free api key sign up at [Ip Stack's website](https://ipstack.com).*

If you wish to develop your own location provider, simply create a new class that implements the `LocationProviderInterface` provided in this package. See the existing `WhoIs` and `FreeGeoIP` location provider classes if you need help creating your own location provider.

###  Health Score

50

—

FairBetter than 96% of packages

Maintenance80

Actively maintained with recent releases

Popularity11

Limited adoption so far

Community19

Small or concentrated contributor base

Maturity79

Established project with proven stability

 Bus Factor1

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

Every ~279 days

Recently: every ~668 days

Total

12

Last Release

93d ago

Major Versions

v1.2.1 → v2.0.02018-10-21

v2.0.1 → v3.0.02025-05-22

v3.0.0 → v4.0.02026-02-14

v4.0.0 → v5.0.02026-02-14

PHP version history (2 changes)v1.1.2PHP >=7.1.0

v3.0.0PHP ^8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/c580cdf7c14898fff179cdfc1085892091d5d2f49d917873a12365af9ac77c93?d=identicon)[Jord-JD](/maintainers/Jord-JD)

---

Top Contributors

[![Jord-JD](https://avatars.githubusercontent.com/u/650645?v=4)](https://github.com/Jord-JD "Jord-JD (22 commits)")[![peter279k](https://avatars.githubusercontent.com/u/9021747?v=4)](https://github.com/peter279k "peter279k (5 commits)")[![milo526](https://avatars.githubusercontent.com/u/5261909?v=4)](https://github.com/milo526 "milo526 (3 commits)")[![SteJaySulli](https://avatars.githubusercontent.com/u/60765965?v=4)](https://github.com/SteJaySulli "SteJaySulli (1 commits)")

---

Tags

countrygeolocationiplocationphpphp-library

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/jord-jd-php-geolocation/health.svg)

```
[![Health](https://phpackages.com/badges/jord-jd-php-geolocation/health.svg)](https://phpackages.com/packages/jord-jd-php-geolocation)
```

###  Alternatives

[shlinkio/shlink

A self-hosted and PHP-based URL shortener application with CLI and REST interfaces

4.8k4.3k](/packages/shlinkio-shlink)[ralphjsmit/laravel-helpers

A package containing handy helpers for your Laravel-application.

13704.6k2](/packages/ralphjsmit-laravel-helpers)[dhlparcel/magento2-plugin

DHL Parcel plugin for Magento 2

11180.5k2](/packages/dhlparcel-magento2-plugin)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)

PHPackages © 2026

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