Filament Yandex Map Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require kpebedko22/filament-yandex-map
   php artisan vendor:publish --tag="filament-yandex-map-config"
   

   Add API keys to .env:

   YANDEX_MAP_API_KEY=your_api_key
   YANDEX_MAP_SUGGEST_API_KEY=your_suggest_api_key
   

2. First Use Case: Add a map field to a Filament form/resource:

   use Kpebedko22\FilamentYandexMap\Components\YandexMap;
   use Kpebedko22\FilamentYandexMap\Enums\YandexMapMode;
   
   YandexMap::make('location')
       ->mode(YandexMapMode::Placemark)
       ->required()
   

3. Where to Look First:

   • Package README for basic usage
   • config/filament-yandex-map.php for default settings
   • resources/lang/vendor/filament-yandex-map for translations

Implementation Patterns

Common Workflows

1. Basic Form Integration

// In a Filament Form
public static function form(Form $form): Form
{
    return $form
        ->schema([
            YandexMap::make('coordinates')
                ->mode(YandexMapMode::Placemark)
                ->columnSpanFull(),
        ]);
}

2. Table Column Display

// In a Filament Table
YandexMap::make('location')
    ->mode(YandexMapMode::Placemark)
    ->height('300px')
    ->disabled()

3. Dynamic Configuration

YandexMap::make('dynamic_map')
    ->mode(fn (CreateLocation $record) => $record->isPremium ? YandexMapMode::Route : YandexMapMode::Placemark)
    ->apiKey(fn () => config('services.yandex_map.api_key'))

4. Validation & Rules

YandexMap::make('required_location')
    ->mode(YandexMapMode::Placemark)
    ->rules(['required', 'yandex_map:required'])

v5.1.0 fixed a bug where PolygonRule reported errors using the polyline translation key. If you validate polygon input and see the wrong message, upgrade to >=5.1.0.

5. Customizing Controls

YandexMap::make('custom_controls')
    ->mode(YandexMapMode::Placemark)
    ->deleteBtnParameters(
        new ButtonData('Delete Marker'),
        new ButtonOptions(float: ButtonFloat::Right)
    )
    ->saveBtnParameters(
        new ButtonData('Save Location'),
        new ButtonOptions(float: ButtonFloat::Left)
    )

6. MultiPolygon Areas (v5.1.0+)

Draw multiple independent polygons in a single field — useful for service areas, delivery zones, or territory coverage that can't be expressed with a single polygon:

YandexMap::make('service_areas')
    ->mode(YandexMapMode::MultiPolygon)
    ->columnSpanFull();

// Persisted state is a collection/array of polygons, so iterate when rendering
foreach ($record->service_areas as $polygon) {
    // each $polygon is an array of [lat, lng] coordinate pairs
}

Integration Tips

1. API Key Management:

   • Use Laravel's config('services.yandex_map.api_key') for consistency
   • Consider using Laravel Envoy for key rotation

2. Translation Handling:

   • Publish translations if using non-Russian locales:

     php artisan vendor:publish --tag="filament-yandex-map-translations"
     

   • Override specific strings in resources/lang/en/filament-yandex-map.php
   • On v5.1.0, re-publish translations if you previously overrode polygon validation strings — the key used by PolygonRule changed.

3. Performance Optimization:

   • Set appropriate height (default: 600px) based on your layout
   • Use columnSpanFull() for full-width maps in forms
   • MultiPolygon modes serialize larger payloads; keep stored geometries simplified for hot paths.

4. Testing:

   • Mock the Yandex API responses in unit tests:

     $this->mock(YandexMapService::class, function ($mock) {
         $mock->shouldReceive('getGeocode')
             ->andReturn(['coordinates' => [55.75, 37.62]]);
     });
     

   • v5.1.0 added coverage for the internal state handlers, so state-mutation regressions are now caught upstream — lean on the released behavior rather than re-testing handler internals yourself.

Gotchas and Tips

Pitfalls

1. API Key Requirements:

   • Both api_key and suggest_api_key are mandatory. Missing either will break the map.
   • Debug Tip: Check browser console for 403 Forbidden errors if keys are invalid.

2. Mode Configuration:

   • mode() is required. Forgetting this will throw a runtime error.
   • Supported modes: Placemark, Route, Polygon, Circle, and MultiPolygon (added in v5.1.0).
   • MultiPolygon state shape differs from Polygon — a single polygon is one coordinate ring, a multipolygon is a list of rings. Migrating an existing Polygon column requires wrapping the old value in an array.

3. Coordinate Validation:

   • Yandex expects coordinates in [latitude, longitude] format. Reversing these will place markers in the ocean.
   • Debug Tip: Use dd($record->coordinates) to verify format.

4. Translation Conflicts:

   • If translations don’t load, clear published views:

     php artisan view:clear
     

   • Stale published polygon rules prior to v5.1.0 may show the polyline error message; clear cached translations after upgrading.

5. CORS Issues:

   • If using the map in an iframe or cross-origin context, ensure Yandex API allows your domain.
   • Fix: Add https://yourdomain.com to Yandex API’s allowed domains.

Debugging Tips

1. Console Errors:

   • Check browser console for Yandex API errors (e.g., YMAP_ERROR).
   • Common issues:
     • API key invalid → Verify .env keys.
     • Geocoder failed → Check suggest_api_key.

2. Network Tab:

   • Inspect failed requests to api-maps.yandex.ru for clues.

3. Log Configuration:

   • Enable debug mode in config/filament-yandex-map.php:

     'debug' => env('APP_DEBUG', false),
     

   • Logs will appear in storage/logs/filament-yandex-map.log.

Extension Points

1. Custom Map Options:

   • Pass additional Yandex Map options via extraOptions():

     ->extraOptions([
         'objectsDisableDefaultBehavior' => true,
         'controls' => ['zoomControl', 'fullscreenControl'],
     ])
     

2. Event Handling:

   • Listen for map events (e.g., marker drag) using JavaScript:

     ->extraOptions([
         'on' => [
             'objectadd' => 'function (e) { console.log(e.get("geometry")); }',
         ],
     ])
     

3. Custom Styling:

   • Override CSS in your Filament panel’s resources/css/filament/app.css:

     .filament-yandex-map-container {
         border: 1px solid #e2e8f0;
         border-radius: 0.5rem;
     }
     

4. Server-Side Processing:

   • Extend the underlying service for custom logic:

     // app/Providers/AppServiceProvider.php
     public function boot()
     {
         $this->app->extend(YandexMapService::class, function ($service) {
             $service->setCustomLogic(function ($data) {
                 // Pre-process coordinates
                 return $data;
             });
             return $service;
         });
     }
     

5. Testing Components:

   • Use Filament’s testing helpers:

     $this->filament()->withinForm(
         fn (Form $form) => $form->fillForm([
             'coordinates' => [55.75, 37.62],
         ])
     );
     

   • The v5.1.0 state-handler tests are a good reference for asserting round-trips of Polygon/MultiPolygon state in your own test suite.