Download the PHP package mydaniel/laravel-geolocation without Composer

Laravel GeoLocation

A powerful, flexible, and multi-driver geolocation package for Laravel. It provides a simple yet robust way to retrieve geographical information for an IP address from various services.

This package is designed to be highly extensible and resilient, with built-in support for caching, fallback drivers, and an elegant, fluent API.

Features

• Multi-Driver Support: Switch between services with a simple config change.
  • ip-api.com (ipapicom): Supports both free and Pro tiers.
  • ipapi.co (ipapico): Simple and free to use.
  • IPQuery.io (ipquery): A fast and reliable service.
  • iplocate.io (iplocate): Another excellent API-based driver.
  • MaxMind (maxmind): Use local GeoLite2/GeoIP2 databases for offline lookups.
  • Chain Driver (chain): Define a sequence of drivers to try until one succeeds.
  • Null Driver (null): Returns static data, perfect for testing.
• Robust Caching: Automatically caches results to reduce API calls and improve performance. Supports cache tags for easy clearing.
• Fallback & Chain Logic: Built-in support for a simple fallback driver or a more powerful chain of drivers to ensure high availability.
• Rich Location Object: Returns a well-structured DTO with fluent getters and useful helper methods like distanceTo().
• Artisan Commands: Includes convenient commands to test lookups and clear the cache directly from your terminal.
• Extensible Architecture: Easily add your own custom geolocation driver.
• IPv4 & IPv6 Support: Validates and locates both IP address formats.

Installation

You can install the package via Composer:

Next, publish the configuration file using the vendor:publish command:

If you plan to use the MaxMind driver, you should also publish the database file. The package includes a placeholder GeoLite2 database.

Configuration

After publishing, the configuration file will be located at config/geolocation.php. Here you can define your default driver and configure each service.

Driver Configuration

Set your default driver and API keys in your .env file.

Cache Configuration

Caching is enabled by default. You can configure the cache settings in config/geolocation.php or via .env variables.

Usage

The package provides a simple and expressive API. Use the GeoLocation facade to perform lookups.

Basic Lookup

The Location Object

The locate method returns a MyDaniel\GeoLocation\Location object, which has the following getters:

• getIp(): string
• getIsoCode(): ?string
• getCountry(): ?string
• getCity(): ?string
• getState(): ?string
• getPostalCode(): ?string
• getLat(): ?float
• getLon(): ?float
• getTimezone(): ?string
• getContinent(): ?string
• getCurrencyCode(): ?string
• getCurrencyName(): ?string
• getCurrencySymbol(): ?string
• getAsnNumber(): ?int
• getAsnOrganization(): ?string
• isFromCache(): bool
• toArray(): array

Calculating Distance

You can easily calculate the distance between two locations using the distanceTo method.

Checking Cache Status

You can check if the result was retrieved from the cache.

Using a Specific Driver

You can use a specific driver on the fly, overriding the default driver from your config file.

Artisan Commands

The package includes two helpful Artisan commands.

Locate an IP

To quickly test a lookup from your terminal:

Clear the Geolocation Cache

This command will clear only the cache entries created by this package by flushing the geolocation tag.

Extending the Package

You can easily add your own custom driver.

1. Create your driver class and implement the MyDaniel\GeoLocation\Contracts\GeolocationDriver interface.
2. Register your driver in the boot method of a service provider (e.g., app/Providers/AppServiceProvider.php) using the extend method.

3. Set your new driver in the config/geolocation.php file or your .env file: GEOLOCATION_DRIVER=my_driver.

Contributing

Contributions are welcome! Please feel free to fork the repository and submit a pull request.

License

The MIT License (MIT). Please see License File for more information.