How masmaleki/laravel-geolocation works
Project type and purpose
• This is a Laravel “wrapper” package (composer library) that provides a Geo-location lookup service for IPs.
• It plugs into any Laravel 5.5+ app via Package Discovery, exposing a Facade, a Console Command, and a driver-based Lookup Manager.
File structure
Top-level:
• config/geolocation.php – default settings (provider, tokens)
• translations/… – localized country name maps
• src/GeoLocationServiceProvider.php – package bootstrapping & container bindings
• src/Console/GeoLocationCommand.php – artisan CLI integration
• src/Contracts/LookupInterface.php – driver contract
• src/Providers/IpInfo.php – provider implementation (HTTP call to ipinfo.io)
• src/GeoLocationManager.php – resolves & proxies requests to drivers
• src/GeoLocation.php – Facade / static API
• src/GeoLocationDetails.php – domain model for lookup results
• tests/… – PHPUnit coverage of each component
Extract architectural notes from README
• Single-driver for IpInfo today, with plans for MaxMind GeoIP2.
• Exposes a high-level API (Facade & Manager).
• Supports publishing config & translation files into a host app.
Main components & interactions
a. Client code (Laravel app) invokes GeoLocation::lookup($ip) or runs artisan geolocation:lookup.
b. The GeoLocation Facade resolves GeoLocationManager from the IoC container.
c. GeoLocationManager reads config (driver name & credentials).
d. It instantiates the appropriate LookupInterface driver (IpInfo) via ServiceProvider bindings.
e. The driver makes an HTTP request to ipinfo.io (external service).
f. Response JSON is mapped into a GeoLocationDetails object.
g. GeoLocationDetails can be used directly in app code or rendered by the Console Command.
h. Translations are loaded via Laravel’s translator when converting country codes to names.
Architectural patterns & principles
• Service Provider / IoC Container to bind interfaces → implementations.
• Facade pattern exposing static API.
• Manager / Factory pattern to resolve driver instances.
• Contract (LookupInterface) for extensibility (swap in MaxMind driver).
• Single Responsibility: Console command only handles CLI I/O, Manager handles driver resolution, Providers handle HTTP.
• Configuration & Translation publishing for customization.