Search by

netresearch / contexts_geolocation

netresearch

Contexts: Geolocation - Geolocation context types (continent, country, distance) for the contexts extension, using MaxMind GeoIP2 for IP-based location detection.

Package info

github.com/netresearch/t3x-contexts_geolocation

Type:typo3-cms-extension

pkg:composer/netresearch/contexts_geolocation

Security

Advisories: 0

Aikido package health analysis

Transparency log

Statistics

Installs: 15 498

Dependents: 0

Suggesters: 0

Stars: 2

Open Issues: 1

1.0.5 2025-11-20 18:12 UTC

Requires

Requires (Dev)

Suggests

None

Provides

None

Conflicts

None

Replaces

  • typo3-ter/contexts_geolocation: 1.0.5

AGPL-3.0-or-later fb711920fa48f4874321b3375f14393bec263d7a

extensiontypo3contextscontexts_geolocation

Published on Packagist.org on 2025-11-20 18:12 UTC

This package is auto-updated.

Last update: 2026-10-12 17:35:41 UTC

README

Contexts: Geolocation for TYPO3

Latest Stable Version TYPO3 PHP License

CI PHPStan OpenSSF Scorecard SLSA 3 Contributor Covenant

Geolocation-based context types for TYPO3. Show pages and content elements for visitors in specific countries, continents, or within a defined geographic area.

Uses MaxMind GeoIP2 for accurate IP-based location detection.

Features

  • Country context: Target visitors from specific countries (ISO 3166-1 alpha-2 codes).
  • Continent context: Target visitors from specific continents.
  • Distance context: Target visitors within a radius from a geographic point.
  • MaxMind GeoIP2: Uses the modern GeoIP2 library with GeoLite2 or commercial databases.
  • Session caching: Efficient lookups with session-based caching.
  • Proxy support: Uses the client IP address TYPO3 determines, so TYPO3's reverse proxy configuration applies.

Requirements

  • TYPO3 12.4 LTS or 13.4 LTS
  • PHP 8.2 or higher
  • contexts extension: ^4.0 || ^5.0.1 || dev-main with Composer (composer.json), 4.x or 5.x for installations from TER (ext_emconf.php)
  • MaxMind GeoLite2-City database (free) or GeoIP2-City database (commercial)

Installation

Install via Composer:

composer require netresearch/contexts-geolocation

Activate the extension:

vendor/bin/typo3 extension:activate contexts_geolocation

MaxMind GeoLite2 Database Setup

This extension requires a MaxMind GeoIP2 database for IP geolocation.

1. Create a MaxMind Account

Sign up for a free account at MaxMind GeoLite2 Signup.

2. Download the Database

Download "GeoLite2 City" in MMDB format from your MaxMind account and extract it to a location on your server (e.g., /var/lib/GeoIP/GeoLite2-City.mmdb).

Alternatively, use the geoipupdate tool for automatic updates:

# Install on Debian/Ubuntu
apt-get install geoipupdate

# Configure /etc/GeoIP.conf with your credentials
# Run update
geoipupdate

3. Configure the Database Path

Set the environment variable:

# In your .env file
GEOIP_DATABASE_PATH=/var/lib/GeoIP/GeoLite2-City.mmdb

Configuration

Environment Variables

Variable Description Default
GEOIP_DATABASE_PATH Path to the GeoIP2 database file (required)

Proxy Configuration

If your TYPO3 installation is behind a reverse proxy, configure the proxy in TYPO3 itself; the extension then uses the client address TYPO3 reads from X-Forwarded-For:

// config/system/additional.php
$GLOBALS['TYPO3_CONF_VARS']['SYS']['reverseProxyIP'] = '192.0.2.10';
$GLOBALS['TYPO3_CONF_VARS']['SYS']['reverseProxyHeaderMultiValue'] = 'last';

With 'last', TYPO3 takes the address the proxy appended, not one the visitor sent in its own X-Forwarded-For. Use 'first' only if the proxy replaces the header instead of appending to it.

Context Types

Continent Context

Matches visitors based on their continent:

  • AF: Africa
  • AN: Antarctica
  • AS: Asia
  • EU: Europe
  • NA: North America
  • OC: Oceania
  • SA: South America

Country Context

Matches visitors based on their country using ISO 3166-1 alpha-2 codes (e.g., DE, US, FR, GB).

Distance Context

Matches visitors within a specified radius (in kilometers) from a geographic point defined by latitude and longitude.

Note: Distance-based targeting works best with larger radii (50+ km) due to the inherent limitations of IP-based geolocation accuracy.

Accuracy Considerations

IP-based geolocation has inherent limitations:

  • Country detection: Generally very accurate (95%+).
  • Continent detection: Very accurate (derived from country).
  • City/coordinates: Accuracy varies significantly; often only accurate to the metropolitan area.

Visitors using VPNs, proxies, or mobile networks may be geolocated to different locations than their actual physical position.

Migration from v1.x

Version 2.0 is a complete rewrite with breaking changes:

  • New GeoIP library: Uses MaxMind GeoIP2 instead of the legacy PECL geoip extension or PEAR Net_GeoIP.
  • Environment configuration: Database path is now configured via environment variables instead of extension settings.
  • PHP 8.2+ required: Modern PHP features and strict typing.
  • TYPO3 12.4+ required: Drops support for TYPO3 11 and earlier.

Documentation

Full documentation is available at docs.typo3.org (once published) or in the Documentation/ folder of this extension.

Security

What the extension does with visitor IP addresses, what it stores, and which security guarantees it gives and does not give is described in docs/SECURITY-ASSURANCE.md. Report vulnerabilities as described in SECURITY.md.

Contributing

Contributions are welcome! Please submit issues and pull requests on GitHub.

License

This extension is licensed under the AGPL-3.0-or-later.

Credits

Developed and maintained by Netresearch DTT GmbH.