roomies / geolocatable
Geolocate IP addresses using a variety of third-party services
Requires
- php: ^8.3
- illuminate/console: ^11.0
- illuminate/contracts: ^11.0
- illuminate/http: ^11.0
- illuminate/support: ^11.0
- spatie/temporary-directory: ^2.2.0
Requires (Dev)
- geoip2/geoip2: ^3.1
- laravel/pint: ^1.0
- mockery/mockery: ^1.6
- orchestra/testbench: ^9.7.0
- phpunit/phpunit: ^11.0
Suggests
- geoip2/geoip2: Required to use the MaxMind database service.
README
Determine the geographical location, currency and network information of website users based on their IP addresses.
Geolocatable is an abstraction over multiple IP geolocation services including Cloudflare, Ip2Location, ipapi.co ipapi.com, ip-api.com, ipdata, Maxmind GeoIP database and web services.
It's based off of laravel-geoip
, but there are some key differences that may affect your decision:
- it allows you to use multiple providers with different configurations,
- it doesn't implement caching behaviour,
- it doesn't implement a fallback/default location.
Installation
You can install the package via Composer:
composer require roomies/geolocatable
You can publish the config file with:
php artisan vendor:publish --tag="geolocatable-config"
Read through the config file to understand the supported services and provide the correct configuration for your preferred services.
Getting started
You can perform an IP address geolcaton using the Facade.
use Roomies\Geolocatable\Facades\Geolocation; // Returns an instance of \Roomies\Geolocatable\Result\Geolocation $result = Geolocate::ip('129.168.0.1'); echo "Looks like you are in {$result->country}, roughly around {$result->latitude}, {$result->longitude}.";
Depending on the provider you choose different combinations of information will be available. It will also depend specifically on the IP address itself and what data the provider has. However, Geolocatable returns a typed readonly class that provides access to structured attributes as well as the raw result if you require it.
- IP address
- location:
Roomies\Geolocatable\Result\Location
- continent name
- country name and country ISO
- state name and state ISO
- city name
- postal code
- latitude
- longitude
- timezone
- network:
Roomies\Geolocatable\Result\Network
- organization
- ISP
- domain
- is a proxy network
- is a mobile network
- is a hosting network
- is an anonymous network
- currency:
Roomies\Geolocatable\Result\Currency
- name
- code
- symbol
- raw: the raw result from the geolocation provider
You can also change the provider you use on the fly.
Geolocate::using('maxmind_database')->ip('192.168.0.1');
Cloudflare
If you have Cloudflare in front of your website you can add visitor location headers
to your app using a managed transform. It doesn't have as much information as other providers and it can only be used for the IP address that makes the request, but it is a great free option if you don't need greater detail.
Ip2Location
Ip2Location is a freemium service that starts at 30,000 lookups/month for free.
Check the config file or provide your IP2LOCATION_KEY
in the environment.
ipapi.co
ipapi is a freemium service.
ipapi.com
Proivide your IPAPI_KEY
API key to use this API.
ip-api.com
ip-api is a freemium service.
ipdata
Provide your IPDATA_KEY
API key to use this API.
Maxmind Database
Provide your Maxmind account_id
and license_key
to download the Maxmind database.
Once configured you need to install the geoip2
dependency and then download the database.
composer require geoip2/geoip2 php artisan geolocatable:download
You can choose to update the database on your own schedule.
Maxmind Web Services
Provide your Maxmind account_id
and license_key
to use Maxmind Web Services.
By default it will use the city
level for IP address details but you can control this.
Testing
Geolocatable includes a fake which makes it easy for you to test how your app handles different results. It allows you to stub the res
$result = new Roomies\Geolocatable\Result\Geolocation( source: 'fake', ipAddress: '192.168.0.1', raw: [] ); Geolocate::fake($result);
License
The MIT License (MIT). Please see License File for more information.