PHPackages                             netresearch/contexts\_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. netresearch/contexts\_geolocation

ActiveTypo3-cms-extension

netresearch/contexts\_geolocation
=================================

Geolocation context types for the contexts extension - match content by country, continent, or distance - by Netresearch

1.0.5(4mo ago)215.5k7[1 issues](https://github.com/netresearch/t3x-contexts_geolocation/issues)AGPL-3.0-or-laterPHPCI passing

Since Jan 10Pushed 2w ago10 watchersCompare

[ Source](https://github.com/netresearch/t3x-contexts_geolocation)[ Packagist](https://packagist.org/packages/netresearch/contexts_geolocation)[ Docs](https://www.netresearch.de)[ RSS](/packages/netresearch-contexts-geolocation/feed)WikiDiscussions main Synced today

READMEChangelog (5)Dependencies (4)Versions (7)Used By (0)

Contexts: Geolocation
=====================

[](#contexts-geolocation)

[![Latest Stable Version](https://camo.githubusercontent.com/16a149eb0e5f8d4c26d03e0871962e3a7f182996361f30b8447830dc87b1cd40/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6e657472657365617263682f636f6e74657874732d67656f6c6f636174696f6e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/netresearch/contexts-geolocation)[![TYPO3](https://camo.githubusercontent.com/628b525928a769ba9fe36fe2a8c5bd6dfe3dbc90cab840985456b91ea4b3526f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5459504f332d31322e3425323025374325323031332e342d6f72616e67652e7376673f7374796c653d666c61742d737175617265)](https://typo3.org/)[![PHP](https://camo.githubusercontent.com/3ab08792c9151922aa5272a343694533ce85b4596bd3bdfb2cf8dce39446314c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322b2d626c75652e7376673f7374796c653d666c61742d737175617265)](https://php.net/)[![License](https://camo.githubusercontent.com/37fced867f9a4f8ee52f429e9949f2ee86d375a0c1c0893eee980c16367e1e06/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4147504c2d2d332e302d2d6f722d2d6c617465722d677265656e2e7376673f7374796c653d666c61742d737175617265)](LICENSE)

[![CI](https://camo.githubusercontent.com/2f65d84eae7ad6df16fd29605932ab0028c80d3d62782c76b83fe47d2b02ec88/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6e657472657365617263682f7433782d636f6e74657874735f67656f6c6f636174696f6e2f63692e796d6c3f6272616e63683d6d61696e267374796c653d666c61742d737175617265266c6162656c3d4349)](https://github.com/netresearch/t3x-contexts_geolocation/actions/workflows/ci.yml)[![PHPStan](https://camo.githubusercontent.com/ee642b8a284b5d771b0a4ff4220c86a966f9d4f651b710666a769fed3658bb97/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d6c6576656c25323031302d627269676874677265656e3f7374796c653d666c61742d737175617265)](https://phpstan.org/)[![OpenSSF Scorecard](https://camo.githubusercontent.com/e64b103223a6de1f588dcc44cc6dd02e76546db69deab1e689d9f954cf49757c/68747470733a2f2f6170692e73636f7265636172642e6465762f70726f6a656374732f6769746875622e636f6d2f6e657472657365617263682f7433782d636f6e74657874735f67656f6c6f636174696f6e2f62616467653f7374796c653d666c61742d737175617265)](https://scorecard.dev/viewer/?uri=github.com/netresearch/t3x-contexts_geolocation)[![SLSA 3](https://camo.githubusercontent.com/dc294f15fb5f1c96307863a1e96860310be940504e7ee370cee94bf4400cbac9/68747470733a2f2f736c73612e6465762f696d616765732f67682d62616467652d6c6576656c332e737667)](https://slsa.dev)[![Contributor Covenant](https://camo.githubusercontent.com/0734538776bfefc6c3a16bce381ed941cb9a9214e04f7c3e876661f8de74daef/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f436f6e7472696275746f72253230436f76656e616e742d332e302d3462616161612e7376673f7374796c653d666c61742d737175617265)](CODE_OF_CONDUCT.md)

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](https://www.maxmind.com/en/geoip2-databases) for accurate IP-based location detection.

Features
--------

[](#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**: Configurable trust for X-Forwarded-For and similar headers.

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

[](#requirements)

- TYPO3 12.4 LTS or 13.4 LTS
- PHP 8.2 or higher
- [contexts](https://github.com/netresearch/t3x-contexts) extension (v4.0+)
- MaxMind GeoLite2-City database (free) or GeoIP2-City database (commercial)

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

[](#installation)

Install via Composer:

```
composer require netresearch/contexts-geolocation
```

Activate the extension:

```
vendor/bin/typo3 extension:activate contexts_geolocation
```

MaxMind GeoLite2 Database Setup
-------------------------------

[](#maxmind-geolite2-database-setup)

This extension requires a MaxMind GeoIP2 database for IP geolocation.

### 1. Create a MaxMind Account

[](#1-create-a-maxmind-account)

Sign up for a free account at [MaxMind GeoLite2 Signup](https://www.maxmind.com/en/geolite2/signup).

### 2. Download the Database

[](#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

[](#3-configure-the-database-path)

Set the environment variable:

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

Configuration
-------------

[](#configuration)

### Environment Variables

[](#environment-variables)

VariableDescriptionDefault`GEOIP_DATABASE_PATH`Path to the GeoIP2 database file(required)`GEOIP_TRUST_PROXY_HEADERS`Trust X-Forwarded-For headers`false`### Proxy Configuration

[](#proxy-configuration)

If your TYPO3 installation is behind a reverse proxy, enable proxy header trust:

```
GEOIP_TRUST_PROXY_HEADERS=true
```

Context Types
-------------

[](#context-types)

### Continent Context

[](#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

[](#country-context)

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

### Distance Context

[](#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
-----------------------

[](#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
-------------------

[](#migration-from-v1x)

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
-------------

[](#documentation)

Full documentation is available at [docs.typo3.org](https://docs.typo3.org/p/netresearch/contexts-geolocation/main/en-us/)(once published) or in the `Documentation/` folder of this extension.

Contributing
------------

[](#contributing)

Contributions are welcome! Please submit issues and pull requests on [GitHub](https://github.com/netresearch/t3x-contexts_geolocation).

License
-------

[](#license)

This extension is licensed under the [AGPL-3.0-or-later](LICENSE).

Credits
-------

[](#credits)

Developed and maintained by [Netresearch DTT GmbH](https://www.netresearch.de/).

- **Website**:
- **GitHub**: [https://github.com/netresearch/t3x-contexts\_geolocation](https://github.com/netresearch/t3x-contexts_geolocation)
- **Issues**: [https://github.com/netresearch/t3x-contexts\_geolocation/issues](https://github.com/netresearch/t3x-contexts_geolocation/issues)

###  Health Score

50

—

FairBetter than 96% of packages

Maintenance78

Regular maintenance activity

Popularity25

Limited adoption so far

Community22

Small or concentrated contributor base

Maturity67

Established project with proven stability

 Bus Factor1

Top contributor holds 68% 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 ~647 days

Recently: every ~357 days

Total

6

Last Release

121d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/acffee6a64e18f21593794b335dd8786001148f7df89fd8372a54d3dd09d91a4?d=identicon)[netresearch](/maintainers/netresearch)

---

Top Contributors

[![CybotTM](https://avatars.githubusercontent.com/u/326348?v=4)](https://github.com/CybotTM "CybotTM (85 commits)")[![magicsunday](https://avatars.githubusercontent.com/u/564393?v=4)](https://github.com/magicsunday "magicsunday (24 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (6 commits)")[![renovate[bot]](https://avatars.githubusercontent.com/in/2740?v=4)](https://github.com/renovate[bot] "renovate[bot] (2 commits)")[![Grony](https://avatars.githubusercontent.com/u/3973389?v=4)](https://github.com/Grony "Grony (2 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (2 commits)")[![just-tobi](https://avatars.githubusercontent.com/u/5242689?v=4)](https://github.com/just-tobi "just-tobi (1 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (1 commits)")[![Gitsko](https://avatars.githubusercontent.com/u/17161911?v=4)](https://github.com/Gitsko "Gitsko (1 commits)")[![mbrodala](https://avatars.githubusercontent.com/u/5037116?v=4)](https://github.com/mbrodala "mbrodala (1 commits)")

---

Tags

geoipgeoip2geolocationmaxmindphptypo3typo3-extensionextensiontypo3contextscontexts\_geolocation

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/netresearch-contexts-geolocation/health.svg)

```
[![Health](https://phpackages.com/badges/netresearch-contexts-geolocation/health.svg)](https://phpackages.com/packages/netresearch-contexts-geolocation)
```

###  Alternatives

[friendsoftypo3/tt-address

Displays a list of addresses from an address table on the page.

461.7M34](/packages/friendsoftypo3-tt-address)[netresearch/contexts

Multi-channel content visibility for TYPO3 - by Netresearch

1116.5k1](/packages/netresearch-contexts)[rupertgermann/tt_news

Website news with front page teasers and article handling inside.

2054.3k](/packages/rupertgermann-tt-news)

PHPackages © 2026

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