Getting Started

Minimal Setup

Install the package:

composer require devrabiul/laravel-geo-genius

Publish config and migrations:

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

Run migrations (if adding timezone columns):
```
php artisan migrate
```

First Use Case: Detect User Location

// In a controller or service
$geoData = laravelGeoGenius()->geo()->locateVisitor();
dd($geoData); // Returns array with country, timezone, IP, etc.

First Use Case: Phone Input Field (Blade)

<!DOCTYPE html>
<html>
<head>
    {!! laravelGeoGenius()->initIntlPhoneInput() !!}
</head>
<body>
    <input type="tel" id="phone" name="phone">
</body>
</html>

First Use Case: Timezone Conversion

$convertedTime = laravelGeoGenius()->timezone()->convertToUserTimezone('2024-01-01 12:00:00');

Implementation Patterns

Core Workflow: User Geo-Detection

Initial Detection (on first request):

$geoData = laravelGeoGenius()->geo()->locateVisitor();

Session Persistence (subsequent requests):

$geoData = laravelGeoGenius()->geo()->getLocationData();

Fallback Handling:

$geoData = laravelGeoGenius()->geo()->getLocationData([
    'fallback' => [
        'country' => 'us',
        'timezone' => 'America/New_York'
    ]
]);

Livewire Integration Pattern

// In Livewire component
public function mount() {
    $this->geoData = laravelGeoGenius()->geo()->getLocationData();
}

public function updatedGeoData() {
    // React to changes (e.g., user manually selects country)
    laravelGeoGenius()->geo()->updateLocationData($this->geoData);
}

Translation Workflow

Add language support:
```
php artisan geo:add-language bn
```

Generate translations:

php artisan geo:translations-generate --locale=bn

Use in code:
```
echo geniusTrans('welcome_message');
```

Phone Input Validation

// In your JS file
const input = document.querySelector("#phone");
const iti = window.intlTelInput(input, {
    initialCountry: document.querySelector('.system-default-country-code').dataset.value,
    // other options...
});

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

Timezone Migration Pattern

// Add timezone column to users table
php artisan geo:add-timezone-column users

// In User model
protected static function boot() {
    parent::boot();

    static::creating(function ($user) {
        $user->timezone = laravelGeoGenius()->timezone()->getUserTimezone();
    });
}

Gotchas and Tips

Common Pitfalls

Session vs Cache Conflicts:
- GeoGenius v1.6+ prioritizes session data over cache. Clear sessions when testing:
```
php artisan session:clear
```
- Tip: Use laravelGeoGenius()->geo()->forceRefresh() to bypass session cache.
IP Detection Issues:
- Localhost (127.0.0.1) returns external IP by default. For testing:
```
laravelGeoGenius()->geo()->setTestIp('8.8.8.8');
```
- Gotcha: Cloudflare/VPN users may get incorrect geolocation. Implement manual override:
```
laravelGeoGenius()->geo()->setLocationData(['country' => 'us']);
```
Translation Quirks:
- Auto-translation requires auto_translate: true in config.
- Tip: Use geniusTranslateNumber() for locale-specific number formatting:
```
echo geniusTranslateNumber(12345, 'bn'); // Bengali digits
```
Phone Input Edge Cases:
- Ensure intl-tel-input CSS/JS is loaded before initialization.
- Debugging: Check for system-default-country-code span in DOM.

Debugging Tips

Inspect Raw Data:

dd(laravelGeoGenius()->geo()->getRawLocationData());

Enable Debug Mode:

laravelGeoGenius()->setDebug(true);
// Check Laravel logs for detailed API responses

Cache Issues:

Clear cache after config changes:

php artisan cache:clear
php artisan config:clear

Extension Points

Custom IP Provider:

laravelGeoGenius()->geo()->setIpProvider(function() {
    return request()->ip() ?? 'custom_ip_here';
});

Override Detection Logic:

laravelGeoGenius()->geo()->extendDetection(function($data) {
    $data['custom_field'] = 'value';
    return $data;
});

Hook into Timezone Conversion:

laravelGeoGenius()->timezone()->extendConversion(function($date, $timezone) {
    // Modify conversion logic
    return $date->setTimezone($timezone);
});

Performance Optimization

Disable Auto-Detection (for non-geo apps):

laravelGeoGenius()->geo()->disableAutoDetection();

Increase Cache TTL (for stable regions):

laravelGeoGenius()->geo()->setCacheTtl(1440); // 24 hours

Batch API Calls (for bulk operations):

laravelGeoGenius()->geo()->batchLocate(['ip1', 'ip2', 'ip3']);

Configuration Quirks

Phone Input Restrictions:
- Set only_countries_mode: true to restrict dropdown:
```
'phone_input' => [
    'only_countries_mode' => true,
    'only_countries_array' => ['us', 'ca', 'uk']
]
```
- Note: Initial country must be in only_countries_array.

Locale Fallback:

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

'language' => [
    'fallback_locales' => ['en', 'bn'],
    'default_locale' => 'en'
]

Timezone Database:
- GeoGenius uses PHP's built-in timezone database. For custom timezones:
```
laravelGeoGenius()->timezone()->addCustomTimezone('Custom/Zone', 'UTC+5');
```

Laravel Geo Genius Laravel Package