README

Laravel GeoGenius is a lightweight, flexible package for Laravel applications that handles:

• ???? Geolocation — Detect user location via IP
• ???? Timezone Management — Detect and convert user timezones automatically
• ????️ Multilingual & Translation Support — Auto-detect locale, translate messages, and even convert numbers
• ???? Country Picker & Phone Validation — Auto-detect default country, show a dropdown of all countries, format and validate numbers automatically

It automatically retrieves detailed IP-based location data, detects the user’s timezone, sets the correct locale, and even initialises a fully-functional phone input field with country picker and validation — all seamlessly integrated into your app.

✅ Fully compatible with Livewire, works via cookies or headers, and enables a truly global-ready Laravel application.

Featured On

I’m proud to share that GeoGenius was featured on Laravel News in their article: “GeoGenius Package for Laravel”.
Read it here: GeoGenius Package for Laravel — Laravel News

???? Live Demo

???? Try the Live Demo

✨ Key Features

• ???? Automatic Timezone Detection — via cookies, headers, or fallback strategies
• ???? Timezone Conversion Helpers — convert timestamps automatically
• ???? Country Picker & Phone Validation — detect visitor’s country, show dropdown, format & validate numbers
• ⚡ Lightweight & Dependency-Free — no jQuery or frontend frameworks required
• ???? Livewire Compatible — works seamlessly with Livewire apps
• ???? Configurable Detection Strategy — customise detection method per app requirements
• ???? Migration & Artisan Support — add timezone column effortlessly
• ???? Caching & Offline Support — reduces API calls and handles offline gracefully
• ???? Multilingual Ready — built-in translation and auto-translation support

Under the hood, it leverages reliable IP geolocation APIs like ipwho.is and ip-api.com with caching for optimal performance.

???? Installation

composer require devrabiul/laravel-geo-genius

Publish the configuration and migration stub:

php artisan vendor:publish --provider="Devrabiul\\LaravelGeoGenius\\LaravelGeoGeniusServiceProvider"

⚡ Quick Start

Use Laravel GeoGenius in two ways:

1. ✅ Global Helper — laravelGeoGenius() (recommended)
2. ???? Service Class — manually instantiate GeoLocationService

Global Helper

laravelGeoGenius()->geo()->locateVisitor();
laravelGeoGenius()->geo()->getCountry();
laravelGeoGenius()->geo()->getTimezone();
laravelGeoGenius()->geo()->getLatitude();

Service Class

use Devrabiul\LaravelGeoGenius\Services\GeoLocationService;

$geo = new GeoLocationService();

$ip = $geo->getClientIp();
$locationData = $geo->locateVisitor();

???? Multilingual & Translation

Built-in auto translation and number conversion:

use function Devrabiul\LaravelGeoGenius\geniusTrans;
use function Devrabiul\LaravelGeoGenius\geniusTranslateNumber;

echo geniusTrans('welcome_message');
echo geniusTranslateNumber(12345); // Bengali digits if locale is 'bn'

Configure in config/laravel-geo-genius.php:

'translate' => [
    'auto_translate' => true,
],

???? Translation Artisan Commands

Laravel GeoGenius provides a set of helpful artisan commands to manage languages and translations easily:

Examples

# 1. Add English language support
php artisan geo:add-language en

# 2. Generate messages.php file from all translate() calls
php artisan geo:translations-generate --locale=en

# 3. Translate up to 100 strings for English
php artisan geo:translate-language en --count=100

# 4. Keep translating until all English strings are done (300 at a time)
php artisan geo:translate-language-all en --count=300

# 5. Translate 50 strings in a batch (useful for automation)
php artisan geo:translate-language-batch en --count=50

???? Change Current User Language

You can programmatically change the current user's language using the changeUserLanguage method:

use Illuminate\Support\Facades\Route;

Route::get('/change-lang', function () {
    // Change current user language to Bengali
    laravelGeoGenius()->language()->changeUserLanguage('bn');

    // Continue your logic
    return redirect()->back();
});

Supported locale codes depend on your configuration (config/laravel-geo-genius.php) and the languages you have added via geo:add-language.

???? Timezone Artisan Commands

Laravel GeoGenius ships with helpful artisan commands:

Examples

# Add Bengali language
php artisan geo:add-language bn

???? Timezone Detection & Conversion

use Devrabiul\LaravelGeoGenius\Services\TimezoneService;

$tz = new TimezoneService();

// Detect user's timezone
$timezone = $tz->getUserTimezone();

// Convert UTC datetime to user timezone
echo $tz->convertToUserTimezone('2025-09-13 15:00:00');

???? Timezone Artisan Commands

Laravel GeoGenius ships with helpful artisan commands:

Examples

# Add a timezone column to the 'users' table
php artisan geo:add-timezone-column users

???? Country Picker & Phone Input

Laravel GeoGenius makes it trivial to initialise a country-aware phone input field:

• Auto-detects visitor’s default country
• Displays country dropdown (or restrict to one country)
• Formats phone numbers as the user types
• Provides built-in validation for numbers

Quick Blade Example

<!DOCTYPE html>
<html lang="{{ app()->getLocale() }}">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>

    {!! laravelGeoGenius()->initIntlPhoneInput() !!}

    <input id="phone" type="tel" name="phone">
</body>
</html>

GeoGenius injects the detected country code into a hidden span:

<span class="system-default-country-code" data-value="us"></span>

Then you can use intl-tel-input’s API to validate on submit:

const input = document.querySelector("#phone");
const iti = window.intlTelInput(input, {
    initialCountry: document.querySelector('.system-default-country-code').dataset.value,
    utilsScript: "https://cdn.jsdelivr.net/npm/intl-tel-input@19.2.15/build/js/utils.js",
});

form.addEventListener('submit', e => {
    if (!iti.isValidNumber()) {
        e.preventDefault();
        alert('Please enter a valid phone number');
    }
});

All scripts/styles are included automatically by initIntlPhoneInput() — you only need to add the <input> and optionally the validation snippet.

???? Restrict to Specific Countries

Laravel GeoGenius gives you full control over which countries appear in the phone input dropdown. You can either show all countries (default) or restrict it to a specific set such as only the U.S. and Canada.

This behavior is configured in your config/laravel-geo-genius.php file under the phone_input section.

Example Configuration

'phone_input' => [
    'initial_country' => env('GEO_PHONE_DEFAULT_COUNTRY', 'us'),
    'only_countries_mode' => true, // enable restriction mode
    'only_countries_array' => ['us', 'ca'], // allowed countries only
    'auto_insert_dial_code' => false,
    'national_mode' => false,
    'separate_dial_code' => false,
    'show_selected_dial_code' => true,
    'auto_placeholder' => 'off',
],

When only_countries_mode is true, GeoGenius will:

✅ Restrict the dropdown list to countries in only_countries_array ✅ Set the initial_country to the visitor’s detected country (if allowed) ✅ Fallback to the default country if the detected one isn’t in the list

If the mode is disabled (false), all countries are shown automatically.

???? Additional Notes

• ???? APIs Used: ipify.org, ipwho.is
• ???? Caching: Geo data cached 7 days per IP (ttl_minutes = cache lifetime in minutes)
• ⚙️ Fallback: Returns default structure if offline
• ???? Localhost Handling: Fetches external IP for 127.0.0.1 or ::1

???? Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Report bugs through GitHub Issues.

???? Treeware

This package is Treeware. If you use it in production, please buy the world a tree to thank us for our work. Your support helps create employment for local families and restores wildlife habitats.

???? License

MIT License. See LICENSE for details.

???? Support

• ???? Email: devrabiul@gmail.com
• ???? GitHub: devrabiul/laravel-geo-genius
• ???? Packagist: packagist.org/packages/devrabiul/laravel-geo-genius

???? Changelog

See CHANGELOG.md for recent changes and updates.