Download the PHP package movemoveapp/laravel-maxmind without Composer

🌍 Laravel MaxMind

Laravel MaxMind is a simple and flexible package for accessing MaxMind GeoIP2 data passed via Nginx FastCGI parameters.

It allows your Laravel application to read geolocation and ISP information that is resolved by Nginx using the GeoIP2 module, without querying MaxMind databases directly from PHP.

Features

• Automatically parses FastCGI parameters set by Nginx with MaxMind GeoIP2 data
• Supports continent, country, region, city, postal, connection, and ISP data
• Configuration file to override default parameter names
• No need to access MaxMind database from PHP – uses data injected by Nginx

Requirements

• Laravel 10+
• Nginx with ngx_http_geoip2_module
• MaxMind .mmdb database files
• FastCGI configuration passing GeoIP data to PHP

Installation

Register the Service Provider

After installing the package, you need to register the MaxMind service provider.

Laravel 10 and below

Add the following line to the providers array in your config/app.php file:

Laravel 11 and above

Register the service provider in the bootstrap/providers.php file:

Publish the Configuration

To publish the configuration file and customize the package settings, run the following Artisan command:

Configuration

Once published, the configuration file will be available at config/maxmind.php.

This file maps MaxMind geolocation headers to internal configuration keys. You may override the defaults using your .env file. Below are the available environment variables and their default values:

Each configuration key corresponds to a header (typically set via a reverse proxy or edge server like Nginx). You can override any of these defaults by defining the respective environment variable in your .env file.

Nginx Configuration

To ensure that the MaxMind headers are correctly passed to your Laravel application, you need to configure your Nginx (or other reverse proxy) to forward the appropriate HTTP headers. These headers typically come from services like MaxMind's GeoIP2 or your CDN (e.g., Cloudflare, Fastly, or your own proxy setup).

Below is a sample Nginx configuration that sets the headers based on your upstream data (e.g., using geoip2 module or an external resolver):

Step 1: Enable GeoIP2 in nginx.conf

You must configure the ngx_http_geoip2_module to extract the relevant fields from your MaxMind .mmdb files:

Step 2: Pass GeoIP2 Data via fastcgi_param

In your site configuration (typically under sites-available/your-site.conf), include the following fastcgi_param directives in the location ~ \.php$ block to pass GeoIP2 values to PHP:

⚠️ These parameters will be available in Laravel using $request->server('HTTP_X_CONTINENT_NAME'), etc. The package automatically maps them internally — you don't need to manually extract them in your controller.

Verifying Integration

To verify that your headers are being received:

1. Run php artisan route:clear to refresh routing cache.

2. Create a debug route:

3. Access /debug-geo in your browser and check for HTTP_X_CONTINENT_NAME, HTTP_X_COUNTRY_NAME, etc.

Helpers

Detect IP type

Then you can use the detectIpType function like this: