GeoIP — MaxMind GeoLite2 geolocation module

[maximus]

Hey everyone,

I've been building a e-commerce project and needed to show personalized content based on visitor location — shipping availability, regional pricing, state-level compliance notices. Nothing like this existed in the PW ecosystem, so I built it.

What it does

Detects country, region and city from the visitor IP using MaxMind GeoLite2 databases (free). Result is cached in session. Exposes $geoip as a wire variable — available in every template automatically, just like $page or $user.

// That's it. No setup, no require, just use it.
if ($geoip->inCountry('US')) {
    echo $page->us_content;
}

API

// Boolean checks — accept single value or array
$geoip->inCountry('US')
$geoip->inCountry(['US', 'CA', 'GB'])
$geoip->inRegion('GA')                  // ISO 3166-2 subdivision code
$geoip->inRegion(['GA', 'NJ', 'NY'])
$geoip->inCity('Atlanta')

// Inline conditional with optional fallback
echo $geoip->showIf('countryCode', 'US', $page->us_block, $page->global_block);
echo $geoip->showIf('regionCode', ['GA', 'NJ', 'NY'], $page->northeast_promo);
echo $geoip->showIf('continent', 'Europe', $page->eu_gdpr_notice);

// Single field
$geoip->getField('countryCode')   // "US"
$geoip->getField('regionCode')    // "GA"
$geoip->getField('city')          // "Atlanta"
$geoip->getField('timezone')      // "America/New_York"

// Full array
$geo = $geoip->detect();
// ip, country, countryCode, continent, region, regionCode,
// city, zip, lat, lon, timezone, corrected, status

Combining conditions

// Country + region
if ($geoip->inCountry('US') && $geoip->inRegion('CA')) {
    echo $page->california_prop65_notice;
}

// Logged-in + location
if ($user->isLoggedIn() && $geoip->inCountry('US')) {
    echo $page->us_member_block;
}

// Time-of-day in visitor's timezone
$tz   = $geoip->getField('timezone') ?: 'UTC';
$hour = (int) (new DateTime('now', new DateTimeZone($tz)))->format('H');
if ($geoip->inCountry('US') && $hour >= 9 && $hour < 17) {
    echo 'Our US office is open right now.';
}

// Pre-select shipping dropdown (Vivino-style)
$selectedCountry = $geoip->getField('countryCode') ?: 'US';
$selectedState   = $geoip->getField('regionCode')  ?: '';

User location correction

Frontend widget lets visitors fix incorrectly detected location. Stored per-IP in DB, applied on subsequent requests. You can also build your own UI — just POST to /?geoip_action=correct with country_code, region_code, city.

Setup

Composer package and databases live in site/assets/GeoIP/ — not in the module directory, so they survive updates.

cd /path/to/site/assets/GeoIP/ && composer require geoip2/geoip2

Then drop GeoLite2-City.mmdb (or GeoLite2-Country.mmdb) in the same folder. Free download from maxmind.com. The module config page shows the exact path and command for your server.

Admin panel

Setup → GeoIP — lookup log with country/region/city, corrections manager, manual IP lookup tool.

---

GitHub: https://github.com/mxmsmnv/GeoIP
License: MIT
Requires: ProcessWire 3.0.200+, PHP 8.2+

Feedback welcome — especially if you're doing anything geo-based with ProcessWire.

Maxim

[HMCB]

Wow. This is incredible. Thank you for how thorough it appears to be.

[strandoo]

This looks great! Any way to install it without Composer?

[maximus]

Yes. Composer is only needed to build the `vendor/` folder; the module does not need Composer on the server at runtime.

You can run this locally:

cd /path/to/site/assets/GeoIP/
composer require geoip2/geoip2

Then upload the whole `site/assets/GeoIP/` folder to the server, including:

site/assets/GeoIP/vendor/autoload.php
site/assets/GeoIP/GeoLite2-City.mmdb

The module looks for the autoloader at:

site/assets/GeoIP/vendor/autoload.php

So as long as that file and the GeoLite2 database are there, it should work without Composer installed on the hosting server.