devrabiul/laravel-geo-genius

Laravel GeoGenius — A powerful, intelligent toolkit for geo-location, timezone, and locale-based features in Laravel applications.

v1.4 2025-10-14 16:08 UTC

Requires

• php: ^8.0

MIT

• Muhammad Rabiul

• geo
• locale
• geolocation
• laravel
• timezone
• datetime
• internationalization
• IP Location
• timezone detection
• timezone conversion
• user timezone
• laravel timezone
• geo genius
• region detection
• country detection
• context-aware

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:

Command	Description
php artisan geo:add-language {locale}	Create a new language directory with starter files (e.g. en, bn).
php artisan geo:translations-generate --locale={locale}	Scan your app for translate('...') calls and auto-generate messages.php.
php artisan geo:translate-language {locale} --count={n}	Translate up to n messages from new-messages.php into messages.php.
php artisan geo:translate-language-all {locale} --count={n}	Keep running batch translations until all strings are translated.
php artisan geo:translate-language-batch {locale} --count={n}	Translate a fixed batch of n messages at a time.

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:

Command	Description
php artisan geo:add-language {locale}	Add a new language (e.g. en, bn) to your app.

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:

Command	Description
php artisan geo:add-timezone-column {table}	Add a nullable timezone column to the specified table if it does not exist.

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: [e-mail]
• 🌐 GitHub: devrabiul/laravel-geo-genius
• 📦 Packagist: packagist.org/packages/devrabiul/laravel-geo-genius

🔄 Changelog

See CHANGELOG.md for recent changes and updates.