Maxmind Geoip Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require cravler/maxmind-geoip-bundle:3.x-dev
   

   • Flex auto-enables the bundle; otherwise, manually add it to config/bundles.php.

2. Download MaxMind Databases

   • Place .mmdb files (e.g., GeoIP2-Country.mmdb) in resources/MaxMind/ (default path).
   • Example files: MaxMind Downloads.

3. Basic Usage Inject the service in a controller/service:

   use Cravler\MaxMindGeoIpBundle\Service\GeoIpService;
   
   public function __construct(private GeoIpService $geoIp) {}
   
   public function getGeoData(Request $request) {
       $ip = $request->getClientIp();
       $country = $this->geoIp->getCountry($ip);
       return $country->getCountry()->getIsoCode();
   }
   

Implementation Patterns

Core Workflows

1. IP Lookup

   • Use GeoIpService for direct queries:

     $country = $this->geoIp->getCountry($ip);
     $city = $this->geoIp->getCity($ip);
     

   • Chain methods for granular data:

     $data = $this->geoIp->getCity($ip)->getLocation();
     

2. Request Integration

   • Attach geo-data to Symfony’s Request via an event subscriber:

     // src/EventSubscriber/GeoIpSubscriber.php
     public function onKernelRequest(GetResponseEvent $event) {
         $request = $event->getRequest();
         $request->attributes->set('geo', $this->geoIp->getAll($request->getClientIp()));
     }
     

3. Caching

   • Cache responses (e.g., with Symfony Cache) to avoid repeated DB lookups:

     $cache = $this->cache->get($ip, function() use ($ip) {
         return $this->geoIp->getCountry($ip);
     });
     

4. Configuration Overrides

   • Customize paths/databases in config/packages/cravler_max_mind_geo_ip.yaml:

     cravler_max_mind_geo_ip:
         path: '%kernel.project_dir%/var/geoip'
         db:
             country: 'custom-country.mmdb'
     

5. Dependency Injection

   • Tag services for lazy-loading or custom logic:

     services:
         App\Service\GeoIpDecorator:
             decorates: cravler_max_mind_geo_ip.geo_ip
             arguments: ['@cravler_max_mind_geo_ip.geo_ip.decorated']
     

Gotchas and Tips

Pitfalls

1. Database Paths

   • Issue: Bundle expects .mmdb files in resources/MaxMind/ by default.
   • Fix: Override path in config or ensure files are symlinked.

2. Missing Databases

   • Issue: getCity() fails if GeoIP2-City.mmdb is missing.
   • Fix: Validate required files exist in config/packages/ or use source to disable unused DBs.

3. IPv6 Support

   • Issue: Some MaxMind DBs may not handle IPv6 well.
   • Fix: Normalize IPs to IPv4 or use filter_var($ip, FILTER_VALIDATE_IP) before lookup.

4. Performance

   • Issue: Large DBs (e.g., GeoIP2-City.mmdb) slow down first requests.
   • Fix: Preload data in a warmup command or use OPcache.

5. License Key

   • Issue: Cloud/GeoIP2 Accuracy requires a license key.
   • Fix: Set license_key in config or use free GeoLite2 databases.

Debugging

• Enable Verbose Logging Add to config/packages/dev/cravler_max_mind_geo_ip.yaml:

  client:
      options:
          verbose: true
  

• Check Database Validity Use MaxMind’s mmdbdump tool to verify .mmdb files:

  mmdbdump -i GeoIP2-Country.mmdb -b 1.1.1.1
  

Extension Points

1. Custom Data Mappers Extend GeoIpService to add domain-specific logic:

   class CustomGeoIpService extends GeoIpService {
       public function getRiskScore($ip) {
           $asn = $this->getAsn($ip);
           // Custom risk logic...
       }
   }
   

2. Event Dispatching Trigger events on geo-data retrieval:

   $this->eventDispatcher->dispatch(
       new GeoIpEvent($ip, $data),
       GeoIpEvents::ON_GEO_DATA_RETRIEVED
   );
   

3. Cloud API Fallback Combine local DBs with MaxMind’s Cloud API:

   public function getCountry($ip) {
       try {
           return parent::getCountry($ip);
       } catch (Exception $e) {
           return $this->cloudClient->lookup($ip);
       }
   }
   

4. Testing Mock GeoIpService in tests:

   $this->geoIp->method('getCountry')
       ->willReturn(new Country(['isoCode' => 'US']));