Filament Ip To Country Flag Column Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require mohammadhprp/filament-ip-to-country-flag-column
   

   For Filament v2:

   composer require mohammadhprp/filament-ip-to-country-flag-column:"^0.2.0"
   

2. Publish assets (if needed):

   php artisan vendor:publish --provider="Mohammadhprp\IPToCountryFlagColumn\IPToCountryFlagColumnServiceProvider"
   

3. First Usage: Add the column to a Filament table resource:

   use Mohammadhprp\IPToCountryFlagColumn\Columns\IPToCountryFlagColumn;
   
   IPToCountryFlagColumn::make('ip_address_column_name')
       ->label('Country');
   

First Use Case

Display country flags for user IPs in a Filament admin panel table (e.g., UserResource):

// app/Filament/Resources/UserResource/Table.php
public function table(Table $table): Table
{
    return $table
        ->columns([
            // ... other columns
            IPToCountryFlagColumn::make('ip_address')
                ->label('Location')
                ->flagPosition('right'), // Optional: Position flag
        ]);
}

Implementation Patterns

Common Workflows

1. Basic Integration:

   • Use IPToCountryFlagColumn::make('ip_column_name') in table definitions.
   • Works seamlessly with Filament’s Table builder (v1/v2).

2. Dynamic IP Handling:

   • For dynamic IPs (e.g., from request()->ip()), use a computed column:

     use Filament\Tables\Columns\Column;
     
     Column::make('ip_address')
         ->getStateUsing(fn () => request()->ip())
         ->copyable()
         ->badge(),
     IPToCountryFlagColumn::make('ip_address')
         ->label('Visitor Location'),
     

3. Caching for Performance:

   • Cache API responses to avoid repeated calls (see Gotchas for implementation).

4. Multi-Column Layouts:

   • Combine with other columns for richer UIs:

     IPToCountryFlagColumn::make('ip')
         ->label('Country')
         ->flagPosition('left'),
     TextColumn::make('ip')
         ->label('IP Address')
         ->copyable(),
     

Integration Tips

• Filament v2: Ensure compatibility by checking the ^0.2.0 constraint.
• API Key: Register a free API key at iplocation.com and set it in .env:

  IP_TO_COUNTRY_FLAG_API_KEY=your_api_key_here
  

• Fallback for Missing IPs: Use defaultFlag() to show a fallback (e.g., "?" or a neutral flag):

  IPToCountryFlagColumn::make('ip')
      ->defaultFlag('🌍'); // Unicode fallback
  

Gotchas and Tips

Pitfalls

1. API Rate Limits:

   • The free tier of iplocation.com has limited requests/day. Monitor usage in Filament tables with many rows.
   • Fix: Implement caching (e.g., Laravel’s cache()->remember):

     use Illuminate\Support\Facades\Cache;
     
     IPToCountryFlagColumn::make('ip')
         ->getStateUsing(fn ($record) => Cache::remember(
             "ip_flag_{$record->ip}",
             now()->addHours(1),
             fn () => $this->fetchFlagFromApi($record->ip)
         ));
     

2. IP Format Mismatches:

   • Ensure the column’s IP values are valid (e.g., 192.168.1.1 or 2001:0db8::1). Invalid IPs may break the column.
   • Fix: Validate IPs in your model or use a computed column with sanitization.

3. Flag Position Conflicts:

   • If using flagPosition('left') with long text, the flag may overlap content.
   • Fix: Adjust CSS or use flagPosition('right') for right-aligned columns.

4. Filament v1 vs. v2:

   • The package may have minor syntax differences. Check the releases for v2-specific changes.

Debugging

• No Flags Displaying?:

  • Verify the API key is set in .env.
  • Check browser DevTools Network tab for API errors (e.g., 403 Forbidden).
  • Test with a hardcoded IP (e.g., '8.8.8.8') to isolate issues.

• Slow Load Times:

  • The API call is synchronous. For large tables, consider:
    • Lazy-loading flags on hover (custom JS).
    • Pre-fetching flags via a background job (e.g., Laravel Queues).

Extension Points

1. Custom Flag Sources:

   • Override the API client by binding a custom service:

     // app/Providers/AppServiceProvider.php
     public function register()
     {
         $this->app->bind(
             \Mohammadhprp\IPToCountryFlagColumn\Contracts\FlagFetcher::class,
             \App\Services\CustomFlagFetcher::class
         );
     }
     

2. Styling:

   • Customize flags via CSS (target .filament-ip-to-country-flag):

     .filament-ip-to-country-flag img {
         width: 24px;
         height: auto;
         border-radius: 4px;
     }
     

3. Local Development:

   • Mock the API response for testing:

     // tests/TestCase.php
     public function mockFlagApi()
     {
         \Mockery::mock('overload:' . \Mohammadhprp\IPToCountryFlagColumn\Contracts\FlagFetcher::class)
             ->shouldReceive('getFlag')
             ->andReturn('🇺🇸');
     }