Geolocation Laravel Package

Getting Started

• Install via Composer: composer require midnite81/geolocation. If upgrading from v3, do not skip the upgrade notes — v4 is a breaking release (Ip2Location was added as a driver, which almost certainly means the config shape, driver binding, or default service contract changed).
• Start by reading the package README's upgrade section, then inspect config/geolocation.php after running:

  php artisan vendor:publish --provider="Midnite81\GeoLocation\GeoLocationServiceProvider"
  

  The driver/default key is where the breaking change will bite you: v3 configs will not map cleanly to v4.
• First use case: resolve a visitor’s location from an IP in a controller or middleware. Typical shape:

  use Midnite81\GeoLocation\Contracts\Services\GeoLocation;
  
  public function show(Request $request, GeoLocation $geo)
  {
      $location = $geo->getLocation($request->ip());
      // $location->getCountry(), ->getCity(), etc.
  }
  

  (Confirm the exact contract/interface name from the README — this is the single biggest v3→v4 break.)
• Look first at: the published config (driver list), the Contracts directory, and the Drivers directory. Those three tell you everything about how to switch providers and what capabilities each supports.

Implementation Patterns

• Driver-per-environment. Configure IP2LOCATION, MAXMIND, an API-based driver, etc. per environment in .env and let the config default key resolve. This lets local/dev use a no-database stub while production uses a real provider.

  // config/geolocation.php (v4 shape — verify keys against README)
  'default' => env('GEOLOCATION_DRIVER', 'ip2location'),
  'drivers' => [
      'ip2location' => [
          'database' => env('IP2LOCATION_DB_PATH'),
          'mode' => env('IP2LOCATION_MODE', 'bin'),
      ],
  ],
  

• Inject the contract, not the concrete driver. Type-hint the service interface so Laravel’s container resolves the configured driver. Switching providers then becomes an .env change, not a code change.
• Wrap lookups in your own service. Put a thin LocationService over the package so IP normalization, caching, and fallbacks live in one place and are testable. This is especially important now that v4 adds a second real driver whose return objects may differ.
• Cache aggressively. Geolocation is a network or disk lookup per request. Cache by IP:

  return Cache::remember("geo:{$ip}", now()->addDay(), fn () => $geo->getLocation($ip));
  

  Note that mobile IPs churn; consider shorter TTLs for cellular ranges or cache only country-level data.
• Middleware for personalization. Resolve location once in middleware and stuff it into the request or a singleton so downstream code doesn’t re-query. Pair this with Cache to avoid per-request hits.
• Testing. Bind a fake implementation of the geo contract in tests; never hit the real driver. A small in-memory driver returning fixture locations keeps the suite fast and avoids needing the Ip2Location binary database in CI.

Gotchas and Tips

• Breaking change surface. v4 adding Ip2Location means at minimum an interface/config change. Before upgrading, diff the README, check composer.lock for the new dependency, and grep your codebase for Midnite81\GeoLocation\ imports — any concrete class references will likely need to become contract references.
• Ip2Location needs a data file. Unlike a pure HTTP driver, Ip2Location’s binary (.BIN) database must be downloaded and kept on disk, and the path supplied in config. Missing/expired DBs fail silently or throw — assert the file exists at boot or in a health check.
• Licensing/updates. Ip2Location databases are licensed and updated on a schedule. Build a reminder or scheduled job to refresh; stale DBs give wrong country results without erroring.
• Private/reserved IPs. 127.0.0.1, 10.x, 192.168.x will return null or an exception depending on the driver. Short-circuit these in your wrapper before calling the package so dev and staging don’t blow up.
• Driver parity is not guaranteed. With MaxMind/IP2Location/API drivers, returned fields (city, ISP, proxy flags) differ. Normalize into your own DTO rather than relying on the package’s object shape, or you’ll couple your app to one driver.
• Debugging. Log the resolved driver name and the queried IP at debug level; the most common bug is “wrong config cached.” Run php artisan config:clear after changing drivers, and check config('geolocation.default') in artisan tinker first.
• Extension point. Custom drivers can usually be registered by implementing the driver contract and mapping it in the config drivers array — check whether v4 added a registration hook, since that’s often the cleanest upgrade path if you were on a custom v3 driver.