PHPackages                             gryfoss/http-cf-geolocation-service - 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. [HTTP & Networking](/categories/http)
4. /
5. gryfoss/http-cf-geolocation-service

ActiveLibrary[HTTP & Networking](/categories/http)

gryfoss/http-cf-geolocation-service
===================================

Wrapper around GeoIP service and CloudFlare functionality which grants ISO code of the detected country during masking of IPs.

v1.1.0(5mo ago)029MITPHPPHP ^8.2CI passing

Since Nov 12Pushed 5mo agoCompare

[ Source](https://github.com/GryfOSS/http-cf-geolocation-service)[ Packagist](https://packagist.org/packages/gryfoss/http-cf-geolocation-service)[ RSS](/packages/gryfoss-http-cf-geolocation-service/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (4)Versions (3)Used By (0)

CFGeolocationService
====================

[](#cfgeolocationservice)

[![CI Tests](https://github.com/GryfOSS/http-cf-geolocation-service/actions/workflows/ci.yml/badge.svg)](https://github.com/GryfOSS/http-cf-geolocation-service/actions/workflows/ci.yml)[![Quick Tests](https://github.com/GryfOSS/http-cf-geolocation-service/actions/workflows/quick-test.yml/badge.svg)](https://github.com/GryfOSS/http-cf-geolocation-service/actions/workflows/quick-test.yml)[![PHP Version](https://camo.githubusercontent.com/7535257ca228724c93658bd52583d4e47a9bab02c356abf6e54c1d575f2151e6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e312532422d626c75652e737667)](https://php.net)[![License: MIT](https://camo.githubusercontent.com/784362b26e4b3546254f1893e778ba64616e362bd6ac791991d2c9e880a3a64e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e2e737667)](LICENSE)

A high-performance PHP service for detecting user geolocation using Cloudflare headers with MaxMind GeoIP database fallback.

🎯 Purpose
---------

[](#-purpose)

**CFGeolocationService** is designed to provide fast and accurate geolocation detection by leveraging Cloudflare's edge network capabilities while maintaining reliability through GeoIP database fallbacks. This dual-strategy approach ensures optimal performance and accuracy for web applications behind Cloudflare's proxy network.

### Key Benefits

[](#key-benefits)

- **🚀 Performance**: Prioritizes Cloudflare headers for instant geolocation (no database lookup required)
- **🛡️ Reliability**: Falls back to MaxMind GeoIP2 database when Cloudflare headers are unavailable
- **🌐 Accuracy**: Uses Cloudflare's global edge network data combined with MaxMind's proven database
- **⚡ Speed**: Minimal overhead with intelligent caching strategy
- **🔒 Security**: Validates all inputs and handles edge cases gracefully

🏗️ How It Works
---------------

[](#️-how-it-works)

```
1. Check CF-IPCountry header → Valid ISO country code? → Return country
                                      ↓
2. Check CF-Connecting-IP header → Valid IP address? → Use for GeoIP lookup
                                      ↓
3. Fall back to Symfony getClientIp() → Perform GeoIP database lookup → Return country

```

### Dual Detection Strategy

[](#dual-detection-strategy)

1. **Primary**: Cloudflare Headers (instant results)

    - `CF-IPCountry`: ISO 3166-1 alpha-2 country code
    - `CF-Connecting-IP`: Real client IP address
2. **Fallback**: GeoIP Database Lookup

    - MaxMind GeoLite2/GeoIP2 Country database
    - Handles cases where CF headers are missing or invalid

🚀 Installation
--------------

[](#-installation)

### Via Composer

[](#via-composer)

```
composer require gryfoss/http-cf-geolocation-service
```

### Requirements

[](#requirements)

- **PHP**: 8.1 or higher
- **Extensions**: mbstring, filter
- **Dependencies**:
    - `symfony/http-foundation` ^7.3
    - `geoip2/geoip2` ^3.2

📖 Usage
-------

[](#-usage)

### Basic Usage

[](#basic-usage)

```