PHPackages                             abivia/geocoding - 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. abivia/geocoding

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

abivia/geocoding
================

Geocoding support.

3.2.0(1mo ago)355[1 issues](https://github.com/abivia/geocoding/issues)MITPHPPHP ^8.2

Since Aug 11Pushed 1mo ago2 watchersCompare

[ Source](https://github.com/abivia/geocoding)[ Packagist](https://packagist.org/packages/abivia/geocoding)[ RSS](/packages/abivia-geocoding/feed)WikiDiscussions main Synced 4w ago

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

Abivia Geocoding
================

[](#abivia-geocoding)

The Abivia geocoding library provides a caching interface to IP address lookup APIs from these sources:

- ipinfo.io
- ipstack.com
- ipapi.co

The library supports both IPv4 and IPv6 addresses and is designed to seamlessly support other IP address geocoding services.

Requirements
------------

[](#requirements)

Geocoding requires:

- PHP 8.2 or higher
- ext-curl to perform API calls
- abivia/cogs for address support
- mlocati/ip-lib for IP address support

PHP does not need to be built with IPv6 support.

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

[](#installation)

Via composer:

`composer require abivia/geocoding`

Caching
-------

[](#caching)

Geocoding comes with two cache handlers designed for light use and a database cache for heavier use. The array cache will retain lookup results for the lifetime of the current request (or session if stored in a session variable). The file cache stores cached data in a text file. Neither offers support for concurrent requests.

The PDO Cache takes a connection to a database, optionally with table names to override the default tables `geocoder_cache_ip`, `geocoder_cache_subnet` and `geocoder_cache_options`. The cache handler will create these tables if they do not already exist.

Applications can create persistent caches by conforming to the CacheHandler interface. Caches support different retention times for lookup hits and lookup misses. In a file cache, the default retention time for a successful lookup is seven days, the default retention time for a failed lookup is one hour. The PDO cache defaults to 30 days for a successful lookup and one hour for a failed lookup.

### Cache Purging

[](#cache-purging)

Array caches are expected to be transient, so there is no purge logic. The file cache runs a purge at the time the cache is loaded. The PDO cache runs at the interval set by the `purgeCacheTime()` method, which defaults to 24 hours. On the first object creation, the last purge time is loaded from the database and cached in the session to reduce overhead.

### Proxy headers

[](#proxy-headers)

The static `getAddressFromHttp()` method now accepts an optional `$proxyHeaders`parameter. If the parameter is null or not provided, and `allowHeaders` is true, GeoCoder looks for `HTTP_CF_CONNECTING_IP`, `HTTP_CLIENT_IP`, and `HTTP_X_FORWARDED_FOR` headers, in that order (more proxies may be added as they are discovered). A `GeoCoder` instance can maintain an independent proxy list.

By default, and address lookup via `Geocoder::lookupHttp()` checks for the `HTTP_X_FORWARDED_FOR`header. However, other services such as CloudFlare use non-standard headers. A call to `Geocoder::addKnownProxyHeaders()` adds all known proxy headers, which are checked for an IP address in order until a valid address is found.

Other proxies can be added or removed by calling `Geocoder::addProxyHeader()`and `Geocoder::removeProxyHeader()`. Header names are converted to uppercase. Headers are checked in the reverse order that they are added, so that the most recently added header is checked first.

Sample Usage
------------

[](#sample-usage)

```
use Abivia\Geocode\Geocoder;
use Abivia\Geocode\LookupService\IpInfoApi;

$geocoder = new Geocoder(IpInfoApi::make());
$info = $geocoder->lookup('4.4.4.4');
echo $info->getLatitude() . ', ' . $info->getLongitude();
```

The geocoder normalizes results from different services using the GeocodeResult interface, but applications can retrieve the service's response through the GeocodeResult::data() method to access extended information.

Example using a file cache
--------------------------

[](#example-using-a-file-cache)

```
use Abivia\Geocode\CacheHandler\FileCache;
use Abivia\Geocode\Geocoder;
use Abivia\Geocode\LookupService\IpInfoApi;

// Get a cache and set the cache time for a hit to six hours
$cache = new FileCache('mycache.json');
$cache->hitCacheTime(6 * 3600);
$geocoder = new Geocoder(IpInfoApi::make(), $cache);
$info = $geocoder->lookup('4.4.4.4');
echo $info->getLatitude() . ', ' . $info->getLongitude();
```

Subnet queries
--------------

[](#subnet-queries)

For the most part from a geolocation perspective, only the first 24 bits of an IPv4 and the first 48 of an IPv6 address are significant. Geocoding provides a "subnet" query that will return the last queries result in the v4 or v6 range. This can reduce the number of queries on the lookup service, increasing performance and (in the case of paid services) reducing costs.

### Subnet Example

[](#subnet-example)

```
use Abivia\Geocode\Geocoder;
use Abivia\Geocode\LookupService\IpInfoApi;

$geocoder = new Geocoder(IpInfoApi::make());

// Assume 4.4.4.4 is not currently cached. This will cause the service to be queried.
$info = $geocoder->lookupSubnet('4.4.4.4');
echo $info->getLatitude() . ', ' . $info->getLongitude();

// This query will return the cached data for 4.4.4.4
$info2 = $geocoder->lookupSubnet('4.4.4.8');
```

Donations welcome
-----------------

[](#donations-welcome)

If you're getting something out of Geocoding, you can sponsor us in any amount you wish using Liberapay [![Liberapay](https://camo.githubusercontent.com/f42d4c8650291eed95d5feb7658604d653ad107d3308fb7e8f269623d7ed65cf/68747470733a2f2f6c69626572617061792e636f6d2f6173736574732f776964676574732f646f6e6174652e737667)](https://liberapay.com/abivia/donate). Liberapay is itself run on donations and takes no fees beyond bank charges.

###  Health Score

47

—

FairBetter than 93% of packages

Maintenance85

Actively maintained with recent releases

Popularity13

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity68

Established project with proven stability

 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

Every ~100 days

Recently: every ~133 days

Total

15

Last Release

45d ago

Major Versions

1.0.1 → 2.0.02022-08-17

2.6.0 → 3.0.02025-10-06

PHP version history (2 changes)1.0.0PHP ^8.1

2.2.0PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/42cd72dce530e94e60853407cdab69ead232423272b482218ae686c740ce0e99?d=identicon)[abivia](/maintainers/abivia)

---

Top Contributors

[![instancezero](https://avatars.githubusercontent.com/u/2599327?v=4)](https://github.com/instancezero "instancezero (22 commits)")

---

Tags

geocodeabivia

### Embed Badge

![Health badge](/badges/abivia-geocoding/health.svg)

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

###  Alternatives

[roundcube/roundcubemail

The Roundcube Webmail suite

7.1k3.2k3](/packages/roundcube-roundcubemail)[shlinkio/shlink

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

5.2k5.6k](/packages/shlinkio-shlink)[spatie/geocoder

Geocoding addresses to coordinates

8585.3M22](/packages/spatie-geocoder)[anthonymartin/geo-location

Powerful GeoCoding library: Retrieve bounding box coordinates, distances between geopoints, point in polygon, get longitude and latitude from addresses and more with GeoLocation for PHP

1881.0M12](/packages/anthonymartin-geo-location)[mediawiki/maps

Adds various mapping features to MediaWiki

85155.1k3](/packages/mediawiki-maps)[dynamic/silverstripe-locator

SilverStripe Locator Module. Show locations on a map. Search by geoposition.

2113.3k1](/packages/dynamic-silverstripe-locator)

PHPackages © 2026

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