Filament Google Maps

https://github.com/cheesegrits/filament-google-maps
Admin
This package provides a comprehensive set of tools for using Google Maps within the Filament PHP...
Tokens:76,095
Snippets:568
Trust Score:8.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Usage Example

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/infolists-map-entry.md

Example of using MapEntry within a Filament infolist schema, demonstrating configuration of zoom, height, and map controls.

```APIDOC
```php
use Cheesegrits\FilamentGoogleMaps\Infolists\MapEntry;
use Filament\Infolists\Infolist;

public function infolist(Infolist $infolist): Infolist
{
    return $infolist->schema([
        TextEntry::make('street'),
        TextEntry::make('city'),
        TextEntry::make('state'),
        TextEntry::make('zip'),
        MapEntry::make('location')
            ->columnSpan(2)
            ->defaultZoom(14)
            ->height('300px')
            ->mapControls([
                'zoomControl' => true,
                'mapTypeControl' => false,
            ]),
    ]);
}
```
```

--------------------------------

### setUp

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/fields-geocomplete.md

Registers the afterStateHydrated hook and geolocate suffix action.

```APIDOC
## setUp

### Description
Registers the `afterStateHydrated` hook (isLocation + geocodeOnLoad behavior) and the geolocate suffix action.

### Method
protected function setUp(): void

### Source
`src/Fields/Geocomplete.php:382`
```

--------------------------------

### Usage Examples

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/fields-geocomplete.md

Examples of using the Geocomplete field in different modes.

```APIDOC
## Usage Examples

### Standalone mode with reverse geocoding

```php
use Cheesegrits\FilamentGoogleMaps\Fields\Geocomplete;

Geocomplete::make('full_address')
    ->types(['address'])
    ->countries(['us'])
    ->placeField('formatted_address')
    ->reverseGeocode([
        'city'   => '%L',
        'zip'    => '%z',
        'state'  => '%A1',
        'street' => '%n %S',
    ])
    ->maxLength(1024)
    ->minChars(3)
    ->prefix('Choose:')
    ->placeholder('Start typing an address ...');
```

### Location mode with server-side geocoding

```php
Geocomplete::make('location') // field name must be the model's computed attribute
    ->isLocation()
    ->geocodeOnLoad()
    ->updateLatLng()
    ->geolocate()
    ->geolocateIcon('heroicon-o-map');
```

### Custom reverse-geocode closure

```php
Geocomplete::make('location')
    ->isLocation()
    ->reverseGeocodeUsing(function (callable $set, array $results) {
        $set('street', $results['address_components'][1]['long_name']);
    });
```
```

--------------------------------

### Install via Composer

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/README.md

Install the package using Composer. Requires Filament V2 and Laravel 9 or later.

```sh
composer install cheesegrits/filament-google-maps
```

--------------------------------

### Example: drawingControl, drawingField, drawingControlPosition, drawingModes

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/fields-map.md

Example usage of the drawing control methods. Adds the drawing toolbar, sets the drawing field to 'drawing', positions the control at the bottom center, and enables circle and polygon modes.

```php
use Cheesegrits\FilamentGoogleMaps\Helpers\MapsHelper;

Map::make('location')
    ->drawingControl()
    ->drawingField('drawing')
    ->drawingControlPosition(MapsHelper::POSITION_BOTTOM_CENTER)
    ->drawingModes(['circle' => true, 'polygon' => true]);
```

--------------------------------

### Install Filament Google Maps package

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/README.md

Use Composer to install the package into your Laravel project.

```sh
composer require cheesegrits/filament-google-maps "^3.0"
```

--------------------------------

### WidgetMap usage example

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/fields-widget-map.md

Configures a WidgetMap field with map controls, markers populated by WidgetMapAction::mountUsing(), clustering, fit-to-bounds, and a column span.

```php
use Cheesegrits\FilamentGoogleMaps\Fields\WidgetMap;
use Cheesegrits\FilamentGoogleMaps\Actions\WidgetMapAction;

WidgetMap::make('widget_map')
    ->mapControls(['zoomControl' => true])
    ->markers(fn () => $this->markers)   // populated by WidgetMapAction::mountUsing()
    ->clustering()
    ->fitToBounds()
    ->columnSpan(2);
```

--------------------------------

### Implement MapTableWidget Class

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/README.md

Example of a full MapTableWidget implementation including table query, columns, and filters.

```php
use Cheesegrits\FilamentGoogleMaps\Widgets\MapTableWidget;

// ...

class DealershipMap extends MapTableWidget
{
    // ...
    protected function getTableQuery(): Builder
    {
        return Dealer::all();
    }

    protected function getTableColumns(): array
    {
        return [
            Tables\Columns\TextColumn::make('name'),
            Tables\Columns\TextColumn::make('state.name'),
            Tables\Columns\TextColumn::make('phone')
                ->searchable(),
            Tables\Columns\TextColumn::make('email')
                ->searchable(),
        ];
    }

    protected function getTableFilters(): array
    {
        return [
            Tables\Filters\SelectFilter::make('state')
                ->label('State')
                ->relationship('state','state_name'),
            MapIsFilter::make('map'),
        ];
    }
    // ...
}
```

--------------------------------

### Using MapsHelper for URLs, Keys, and Coordinates

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/helpers.md

Shows how to use MapsHelper to generate a map URL with libraries, get the server key, normalize coordinates, check for empty locations, and reverse geocode. Requires importing the MapsHelper class.

```php
use Cheesegrits\FilamentGoogleMaps\Helpers\MapsHelper;

$url = MapsHelper::mapsUrl(false, ['drawing']);          // web key + places + drawing libraries
$key = MapsHelper::mapsKey(true);                         // server key for static maps
$latLng = MapsHelper::getLatLng([39.5, -107.7]);
$empty = MapsHelper::isLocationEmpty($latLng);            // false
$address = MapsHelper::reverseGeocode($latLng);           // formatted_address string
```

--------------------------------

### reverseBatch usage example

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/geocoder.md

Example call to reverseBatch, processing Location records with lat/lng fields, using a format array for address components, and setting the 'processed' column.

```php
[$records, $lookups, $updated] = $geocoder->reverseBatch(
    Location::class, 'lat', 'lng',
    ['street' => '%n %S', 'city' => '%L', 'state' => '%A', 'zip' => '%z'],
    'processed', null
);
```

--------------------------------

### autocomplete example

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/fields-map.md

Example usage of the autocomplete method with named arguments: fieldName 'airport_name', types ['airport'], placeField 'name', and countries ['US', 'CA', 'MX'].

```php
Map::make('location')
    ->autocomplete(
        fieldName: 'airport_name',
        types: ['airport'],
        placeField: 'name',
        countries: ['US', 'CA', 'MX'],
    )
```

--------------------------------

### Map Widget Class Structure

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/README.md

Example of a MapWidget class implementation, including data retrieval and marker configuration.

```php
<?php

namespace App\Http\Livewire\Widgets;

use App\Models\Dealerships;
use Cheesegrits\FilamentGoogleMaps\Widgets\MapWidget;

class DealershipMap extends MapWidget
{
    protected static ?string $heading = 'Dealership Locations';

    protected static ?bool $clustering = true;

    protected function getData(): array
    {
        $dealerships = Dealerships::all();

        $data = [];

        foreach ($dealerships as $dealership)
        {
            if ($dealership->latitude && $dealership->longitude)
            {
                /**
                 * Each element in the returned data must be an array
                 * containing a 'location' array of 'lat' and 'lng',
                 * and a 'label' string.
                 * 
                 * You should also aan 'id' attribute for internal use by this plugin. 
                 */
                $data[] = [
                    'location'  => [
                        'lat' => $dealership->latitude,
                        'lng' => $dealership->longitude,
                    ],
                    
                    'label' => $dealership->name,
                    
                    'id' => $dealership->getKey(),
                    
                    /**
                     * Optionally you can provide custom icons for the map markers,
                     * either as scalable SVG's, or PNG, which doesn't support scaling.
                     * If you don't provide icons, the map will use the standard Google marker pin.
                     */
                    'icon' => [
                        'url' => url('images/dealership.svg'),
                        'type' => 'svg',
                        'scale' => [35,35],
                    ],
                ];               
            }
        }

        return $data;
    }
}
```

--------------------------------

### StaticMapAction Usage Example

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/actions.md

Shows how to add the StaticMapAction to a table's bulk actions. Requires importing the action class and including `StaticMapAction::make()` in the returned array.

```php
use Cheesegrits\FilamentGoogleMaps\Actions\StaticMapAction;

protected function getTableBulkActions(): array
{
    return [
        // ...
        StaticMapAction::make(),
    ];
}
```

--------------------------------

### MapEntry usage example in infolist

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/infolists-map-entry.md

Shows how to add a MapEntry to an infolist schema, with column span, default zoom, height, and map controls.

```php
use Cheesegrits\FilamentGoogleMaps\Infolists\MapEntry;
use Filament\Infolists\Infolist;

public function infolist(Infolist $infolist): Infolist
{
    return $infolist->schema([
        TextEntry::make('street'),
        TextEntry::make('city'),
        TextEntry::make('state'),
        TextEntry::make('zip'),
        MapEntry::make('location')
            ->columnSpan(2)
            ->defaultZoom(14)
            ->height('300px')
            ->mapControls([
                'zoomControl' => true,
                'mapTypeControl' => false,
            ]),
    ]);
}
```

--------------------------------

### geocodeBatch usage example

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/geocoder.md

Example call to geocodeBatch, processing up to 1000 records of the Location model, using address fields 'street,city,state,zip' and setting the 'processed' column to 1.

```php
[$records, $lookups, $updated] = $geocoder->geocodeBatch(
    Location::class, 'lat', 'lng', 'street,city,state,zip', 'processed', 1000
);
```

--------------------------------

### make:filament-google-maps-widget command signature and usage

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/commands.md

Defines the make-widget command signature and description, plus an example invocation. The command creates a map or map+table widget, defaulting to map. It refuses names colliding with MapWidget/MapTableWidget, requires getLatLngAttributes() and getComputedLocation() on the model, and uses Filament config paths and stubs. Use --force to overwrite existing files.

```php
protected $signature = 'make:filament-google-maps-widget {name?} {model?} {--R|resource=} {--M|map} {--T|table} {--F|force}';
```

```php
protected $description = 'Creates a Filament Google Maps widget class.';
```

```sh
php artisan fgm:make-widget LocationMapTableWidget Location --table --resource=LocationResource
```

--------------------------------

### Example: geoJson, geoJsonContainsField, geoJsonVisible

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/fields-map.md

Example usage of the GeoJSON methods. Adds a GeoJSON layer from a closure returning raw JSON, sets a field to receive containing feature property values, and hides the layer.

```php
Map::make('location')
    ->geoJson(function () {
        return '{"type":"FeatureCollection","features":[]}';
    })
    ->geoJsonContainsField('geojson_contains', 'prop0')
    ->geoJsonVisible(false);
```

--------------------------------

### placeUpdatedUsing example

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/fields-map.md

Example usage of placeUpdatedUsing to update a form field when a place is selected. The callback receives the place data and a $set callable to update fields, here setting the 'city' field.

```php
Map::make('location')
    ->placeUpdatedUsing(function (callable $set, array $place) {
        $set('city', 'foo wibble');
    });
```

--------------------------------

### Get commands in FilamentGoogleMapsServiceProvider

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/service-provider.md

Returns the six real command classes and appends matching aliases if they exist. Guarded by class_exists to exclude Filament-v2-only aliases.

```php
protected function getCommands(): array
```

--------------------------------

### Geocoder one-off lookups example

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/geocoder.md

Shows how to instantiate Geocoder with a rate limit of 100 calls per minute, perform forward and reverse geocoding, and bypass the cache once using doNotCache(). The reverse method returns the formatted_address string, and doNotCache() disables caching for the next request only.

```php
use Cheesegrits\FilamentGoogleMaps\Helpers\Geocoder;

$geocoder = new Geocoder(100); // max 100 calls/minute

$latLng  = $geocoder->geocode('1600 Pennsylvania Avenue NW, Washington, DC 20500');
$address = $geocoder->reverse(38.8976633, -77.0365739);      // formatted_address
$fresh   = $geocoder->doNotCache()->geocode('10 Downing St'); // bypass cache once
```

--------------------------------

### MapWidget subclass example with clustering and marker action

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/widgets.md

Shows a complete MapWidget subclass that returns dealership locations as map data. The markerAction method name must match static::$markerAction, and the clicked marker's id is passed in the action arguments under the 'model_id' key.

```php
use Cheesegrits\FilamentGoogleMaps\Widgets\MapWidget;

class DealershipMap extends MapWidget
{
    protected static ?string $heading = 'Dealership Locations';

    protected static ?bool $clustering = true;

    protected function getData(): array
    {
        $data = [];

        foreach (Dealership::all() as $dealership) {
            if ($dealership->latitude && $dealership->longitude) {
                $data[] = [
                    'location' => ['lat' => $dealership->latitude, 'lng' => $dealership->longitude],
                    'label'    => $dealership->name,
                    'id'       => $dealership->getKey(),
                ];
            }
        }

        return $data;
    }

    public function markerAction(): \Filament\Actions\Action
    {
        return \Filament\Actions\Action::make('markerAction')
            ->label('Details')
            ->infolist([...])
            ->record(fn (array $arguments) => $arguments['model_id'] ?? null
                ? Location::find($arguments['model_id']) : null)
            ->modalSubmitAction(false);
    }
}
```

--------------------------------

### GET /cheesegrits/filament-google-maps/{file}

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/endpoints.md

Serves a cached static map image (PNG) by filename. The file must exist in the cache with a key matching the filename without extension; otherwise, a 404 is returned.

```APIDOC
## GET /cheesegrits/filament-google-maps/{file}

### Description
Serves a cached static map image (PNG) by filename. The file must exist in the cache with a key matching the filename without extension; otherwise, a 404 is returned.

### Method
GET

### Endpoint
/cheesegrits/filament-google-maps/{file}

### Parameters
#### Path Parameters
- **file** (string) - Required - Filename served by the controller, e.g. `fgm-1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6.png`

### Request Example
```
GET https://example.com/cheesegrits/filament-google-maps/fgm-<md5>.png
```

### Response
#### Success Response (200)
- **Content-Type** (string) - image/png
- **Body** (binary) - Raw cached PNG bytes, streamed via `Response::streamDownload()`
- **Content-Disposition** (string) - File-download disposition attributes provided by Laravel's `streamDownload` (filename = `{file}`)

#### Response Example
```
[Binary PNG data]
```

#### Not Found Response (404)
- Triggered when: the extension is not `png`, the cache key is absent from the configured cache store, or the cache entry has expired (`ttl`/`cache.duration`).
- Body: Laravel default error page.
```

--------------------------------

### Reverse Geocode Output Format

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/README.md

Example output of the reverse-geocode command showing the mapping of symbols to address components.

```shell
php artisan filament-google-maps:reverse-geocode --lat=38.8976633 --lng=-77.0365739
+--------+-------------------------------+
| Symbol | Result                        |
+--------+-------------------------------+
| %n     | 1600                          |
| %S     | Pennsylvania Avenue Northwest |
| %L     | Washington                    |
| %D     |                               |
| %z     | 20502                         |
| %A1    | District of Columbia          |
| %A2    |                               |
| %A3    |                               |
| %A4    |                               |
| %A5    |                               |
| %a1    | DC                            |
| %a2    |                               |
| %a3    |                               |
| %a4    |                               |
| %a5    |                               |
| %C     | United States                 |
| %c     | US                            |
| %T     |                               |
+--------+-------------------------------+
```

--------------------------------

### RadiusFilter

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/filters.md

Documentation for the RadiusFilter class, including its methods, configuration options, and usage examples.

```APIDOC
## RadiusFilter

### Description
Radius filtering of a table against a geocomplete address, in miles (default) or kilometers. Filter form state: `geocomplete` (address string), `radius` (numeric distance), `unit` (`'mi'`/`'km'`), plus hidden `latitude` and `longitude`.

### Methods

#### getColumns

```php
public function getColumns(): array|int|null
```

Returns `4` — the number of columns for the filter form layout.

#### setUp

```php
protected function setUp(): void
```

- `columnSpan(2)`.
- Registers `indicateUsing` producing the active-filter indicator from `filament-google-maps::fgm.radius_filter.indicate` (`'Within :radius :units of :address'`), only when both `geocomplete` and `radius` are present in state.

#### apply

```php
public function apply(Builder $query, array $data = []): Builder
```

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `$query` | `Builder` | yes | Eloquent query builder |
| `$data` | `array` | no | Filter state: `latitude`, `longitude`, `radius`, `unit` |

- No-op unless `latitude`, `longitude` and `distance` are all truthy.
- Unit selection: `selectUnit()` enabled means `unit === 'km'`; otherwise the configured `kilometers()` flag.
- Applies the haversine formula: `((ACOS(SIN(lat*PI/180)*SIN(col_lat*PI/180) + COS(lat*PI/180)*COS(col_lat*PI/180)*COS((lng-col_lng)*PI/180))*180/PI)*60*<multiplier>) < distance`, where multiplier is `1.1515` (miles) or `1.1515*1.609344` (km). Column names come from `getLatitude()`/`getLongitude()`.
- When `queriesRelationships()` is true, wraps the raw SQL in `whereHas($this->getRelationshipName(), ...)`.

#### getFormSchema

```php
public function getFormSchema(): array
```

Schema: a `Group` (column-span full) containing:

- `Geocomplete::make('geocomplete')->label(...)->filterName($this->getName())->lazy()` — the address field
- `TextInput::make('radius')->numeric()->default($this->getRadius() ?? 10)->lazy()`
- `Select::make('unit')` with `mi`/`km` options, defaulting from `getKilometers()`, visible only when `getSelectUnit()` is true, side-by-side with radius when visible
- Hidden `latitude` and `longitude` fields

If `hasSection()` (a section config is set), everything is wrapped in `Fieldset::make($this->getSection())`.

#### Configuration Methods

```php
public function kilometers(bool|Closure $kilometers = true): static
public function radius(bool|Closure $radius = true): static
public function selectUnit(bool|Closure $selectUnit = true): static
public function latitude(string|Closure|null $name): static
public function longitude(string|Closure|null $name): static
public function section(bool|string|Closure|null $section = true): static
public function attribute(string|Closure|null $name): static
```

| Method | Getter | Behavior |
|--------|--------|----------|
| `kilometers(true)` | `getKilometers(): string` | Use (and default the unit select to) kilometers; default `false` (miles) |
| `radius(10)` | `getRadius(): ?int` | Default radius value for the filter (form default `10` when unset) |
| `selectUnit()` | `getSelectUnit(): string` | Show the mile/km selector |
| `latitude('lat')` | `getLatitude(): string` | Latitude column; default `getLatLngAttributes()['lat']` of the table model or relationship model |
| `longitude('lng')` | `getLongitude(): string` | Longitude column; default `getLatLngAttributes()['lng']` |
| `section('Radius Search')` | `getSection(): ?string` | Wrap the filter in a fieldset; `true` uses the translated `fgm.radius_filter.title`; falsy disables |
| `attribute('place.location')` | `getAttribute(): string` | Relationship + computed attribute; default is the filter name |

`isRelationship(): bool` reports whether a relationship is set (from `HasRelationship`).

### Usage

```php
use Cheesegrits\FilamentGoogleMaps\Filters\RadiusFilter;
use Cheesegrits\FilamentGoogleMaps\Actions\RadiusAction;

protected function getTableFilters(): array
{
    return [
        RadiusFilter::make('radius')
            ->latitude('lat')
            ->longitude('lng')
            ->selectUnit()
            ->kilometers()
            ->section('Radius Search'),
    ];
}

protected function getTableActions(): array
{
    return [
        RadiusAction::make(), // must be named the same as the filter ('radius')
    ];
}
```

Related-table locations (a `place` BelongsTo on the events table):

```php
RadiusFilter::make('radius')
    ->attribute('place.location')
    ->color('primary')
    ->icon('heroicon-m-map');
```
```

--------------------------------

### MapTableWidget class example

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/widgets.md

Defines a LocationMapTableWidget extending MapTableWidget. Includes table query, columns with a MapColumn, a MapIsFilter, a GoToAction, and getData() to provide marker coordinates. When MapIsFilter is present, zooming/panning the map filters the table to visible markers.

```php
use Cheesegrits\FilamentGoogleMaps\Widgets\MapTableWidget;
use Cheesegrits\FilamentGoogleMaps\Filters\MapIsFilter;
use Cheesegrits\FilamentGoogleMaps\Actions\GoToAction;
use Cheesegrits\FilamentGoogleMaps\Columns\MapColumn;
use Filament\Tables;

class LocationMapTableWidget extends MapTableWidget
{
    protected static ?string $heading = 'Location Map';

    protected function getTableQuery(): Builder
    {
        return Location::query()->latest();
    }

    protected function getTableColumns(): array
    {
        return [
            Tables\Columns\TextColumn::make('name'),
            MapColumn::make('location')->height(150)->width(250)->type('hybrid')->zoom(15),
        ];
    }

    protected function getTableFilters(): array
    {
        return [
            MapIsFilter::make('map'),
        ];
    }

    protected function getTableActions(): array
    {
        return [
            GoToAction::make()->zoom(14),
        ];
    }

    protected function getData(): array
    {
        $data = [];

        foreach ($this->getRecords() as $location) {
            $data[] = [
                'location' => [
                    'lat' => $location->latitude,
                    'lng' => $location->longitude,
                ],
                'id' => $location->getKey(),
            ];
        }

        return $data;
    }
}
```

--------------------------------

### testReverse usage example

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/geocoder.md

Shows how to call testReverse with a latitude and longitude and iterate over the returned formats, destructuring each row into symbol, value, and component. The comment indicates the expected output for a street number.

```php
$formats = $geocoder->testReverse(38.8976633, -77.0365739, true);

foreach ($formats as [$symbol, $value, $component]) {
    // '%n' => '1600', component 'street_number'
}
```

--------------------------------

### Interactive reverse-geocode command session

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/README.md

Shows the complete interactive terminal session for the `php artisan filament-google-maps:reverse-geocode Location` command. It prompts for latitude/longitude field names, an optional processed field, and then guides the user through mapping address components using format symbols like %n, %S, %L, %A1, and %z. The session includes a test with record ID 1, a rate limit prompt, and a final command summary with the `--fields`, `--lat`, `--lng`, `--processed`, and `--rate-limit` options.

```sh
fgm> php artisan filament-google-maps:reverse-geocode Location

 Name of latitude element on table (e.g. `latitude`):
 > lat

 Name of longitude element on table (e.g. `longitude`):
 > lng
 
 Optional name of field to set to 1 when record is processed (e.g. `processed`)
 > processed

+------------------------------+-------------------------+
| Component                    | Format                  |
+------------------------------+-------------------------+
| Street Number                | %n                      |
| Street Name                  | %S                      |
| City (Locality)              | %L                      |
| City District (Sub-Locality) | %D                      |
| Zipcode (Postal Code)        | %z                      |
| Admin Level Name             | %A1, %A2, %A3, %A4, %A5 |
| Admin Level Code             | %a1, %a2, %a3, %a4, %a5 |
| Country                      | %C                      |
| Country Code                 | %c                      |
| Timezone                     | %T                      |
+------------------------------+-------------------------+
Use the table above to enter your address component mapping.

Google returns a complex set of address components.  You need to tell us how you want
those components mapped on to your database fields.  We use a standard symbolic format
as summarixed in the table above to extract the address components.

Each mapping should be of the form <field name>=<format symbol(s)>, for example
to map (say) a street address to your `street_name` field, you would need ...

street_name=%n %S

... and you might also add ...

city=%L
state=%A2
zip=%z

... or just ...

formatted_address=%s %S, %L, %A2, %z

You may enter as many mappings as you need, enter a blank line to continue.

Test your field mapping.

Yes.  This is complicated.  If you would like us to look up an example record from your table
and show you what all those formats translate to, enter an ID here.  If not, just press enter.

 ID (primary key on table):
 > 1

+--------+-------------------+
| Symbol | Result            |
+--------+-------------------+
| %n     | 19225             |
| %S     | North 44th Avenue |
| %L     | Glendale          |
| %D     |                   |
| %z     | 85308             |
| %A1    | Arizona           |
| %A2    | Maricopa County   |
| %A3    |                   |
| %A4    |                   |
| %A5    |                   |
| %a1    | AZ                |
| %a2    | Maricopa County   |
| %a3    |                   |
| %a4    |                   |
| %a5    |                   |
| %C     | United States     |
| %c     | US                |
| %T     |                   |
+--------+-------------------+

 Field mapping (e.g. city=%L), blank line to continue:
 > street=%n %S

 Field mapping (e.g. city=%L), blank line to continue:
 > city=%L

 Field mapping (e.g. city=%L), blank line to continue:
 > state=%A1

 Field mapping (e.g. city=%L), blank line to continue:
 > zip=%z

 Field mapping (e.g. city=%L), blank line to continue:
 > formatted_address=%n %S, %L, %z %a1

 Field mapping (e.g. city=%L), blank line to continue:
 > 

 Rate limit as API calls per minute (max 300):
 > 100

Results
API Lookups: 2
Records Updated: 2

Command summary - you may wish to copy and save this somewhere!
php artisan filament-google-maps:reverse-geocode Location --fields="street=%n %S" --fields="city=%L" --fields="state=%A1" --fields="zip=%z" --fields="formatted_address=%n %S, %L, %z %a1" --lat=lat --lng=lng --processed=processed --rate-limit=100

```

--------------------------------

### geolocate example

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/fields-map.md

Example usage of geolocate, geolocateLabel, and geolocateOnLoad. The comment notes that geolocateOnLoad(true, false) geolocates only when the form has no stored location.

```php
Map::make('location')
    ->geolocate()
    ->geolocateLabel('Get Location')
    ->geolocateOnLoad(true, false) // geolocate only when the form has no stored location
```

--------------------------------

### mount method signature

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/widgets.md

Initializes the data checksum to detect changes on first update.

```php
public function mount()
```

--------------------------------

### reverseGeocodeUsing example

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/fields-map.md

Example usage of reverseGeocodeUsing in a Filament EditRecord form. The callback receives the reverse geocode results and a $set callable to update form fields, here setting the 'street' field from the address components.

```php
use Cheesegrits\FilamentGoogleMaps\Concerns\InteractsWithMaps;

class EditLocation extends EditRecord
{
    use InteractsWithMaps;

    public function form(Form $form): Form
    {
        return $form->schema([
            Map::make('location')
                ->reverseGeocodeUsing(function (callable $set, array $results) {
                    $set('street', $results['address_components'][1]['long_name']);
                }),
        ]);
    }
}
```

--------------------------------

### Configure package in FilamentGoogleMapsServiceProvider

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/service-provider.md

Configures the package: sets the name, registers commands, config file, web routes, translations, and views. The first block is the method signature; the second is the body.

```php
public function configurePackage(Package $package): void
```

```php
$package
    ->name('filament-google-maps')
    ->hasCommands($this->getCommands())
    ->hasConfigFile()
    ->hasRoutes(['web'])
    ->hasTranslations()
    ->hasViews();
```

--------------------------------

### GoToAction

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/actions.md

Documentation for the GoToAction class, including its methods and configuration.

```APIDOC
## GoToAction::getDefaultName

### Description
Returns the default name for the action, which is `'setmapcenter'`.

### Method
`public static function getDefaultName(): ?string`

### Returns
- `?string` - The default action name `'setmapcenter'`.

## GoToAction::zoom

### Description
Sets the zoom level used when centering the map on the record's location.

### Method
`public function zoom($zoom): static`

### Parameters
- `$zoom` (mixed) - Required - The zoom level to set.

### Returns
- `static` - The action instance for chaining.

## GoToAction::getZoom

### Description
Gets the zoom level, defaulting to `8` if not set.

### Method
`public function getZoom(): ?int`

### Returns
- `?int` - The zoom level, or `8` if not set.

## GoToAction::setUp

### Description
Configures the action with a label, color, icon, and an Alpine click handler that dispatches a browser event to set the map center.

### Method
`protected function setUp(): void`

### Behavior
- Sets label to `'filament-google-maps::fgm.goto_action.button.label'` ("Go To").
- Sets color to `'danger'` and icon to `'heroicon-s-map'`.
- Disables the Livewire click handler.
- Adds an Alpine `x-on:click` attribute that dispatches the `filament-google-maps::widget/setMapCenter` event with `{lat, lng, zoom}` from the record's latitude/longitude attributes, rounded to 8 decimals.

### Usage Example
```php
use Cheesegrits\FilamentGoogleMaps\Actions\GoToAction;

protected function getTableActions(): array
{
    return [
        GoToAction::make()
            ->zoom(14),
    ];
}
```
```

--------------------------------

### height / width / size method signatures

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/columns-map-column.md

Set image dimensions in pixels. Defaults are height=150 and width=200. size() sets both width and height identically.

```php
public function height(int|Closure $height): static
public function width(int|string|Closure|null $width): static
public function size(int|string|Closure $size): static
```

--------------------------------

### minChars

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/fields-geocomplete.md

Minimum characters typed before autocomplete starts searching.

```APIDOC
## minChars

### Description
Minimum characters typed before autocomplete starts searching (default `0`; the README recommends 3).

### Method
`public function minChars(int $minChars): static`

### Parameters
- **$minChars** (int) - Required - The minimum number of characters.

### Returns
- static - The current instance for chaining.

### Getter
`getMinChars(): int`

### Source
`src/Fields/Geocomplete.php:463`
```

--------------------------------

### MapsHelper::getCountyFromAddress

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/helpers.md

Gets the county from an address via geocoding.

```APIDOC
## MapsHelper::getCountyFromAddress

### Description
Geocodes an address and extracts the admin level 2 (county) component.

### Method
`public static function getCountyFromAddress(string $address): string`

### Parameters
- **$address** (string) - Required - The address to geocode.

### Returns
- **string** - The county name, or `''` if not found.

### Example
```php
$county = MapsHelper::getCountyFromAddress('1600 Amphitheatre Pkwy');
```
```

--------------------------------

### Frontend Widget Invocation

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/README.md

Instructions for using a widget on the front end by moving it to the Livewire folder and invoking it via Blade.

```shell
Your widget has been created as: App/Filament/Resources/LocationMapTableWidget.php

If you want to use it on the front end, copy/move it to somewhere in your Livewire folder, say ...

/Http/Livewire/Widgets/LocationMapTableWidget.php

... and then invoke it from a front end Blade template like ...

@livewire('widgets.location_map_table_widget')
```

--------------------------------

### MapsHelper::getCountyFromLatLng

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/helpers.md

Gets the county from coordinates via reverse geocoding.

```APIDOC
## MapsHelper::getCountyFromLatLng

### Description
Reverse geocodes coordinates and extracts the admin level 2 (county) component.

### Method
`public static function getCountyFromLatLng(array|string $lat, ?string $lng = null): string`

### Parameters
- **$lat** (array|string) - Required - Latitude or an array of coordinates.
- **$lng** (?string) - Optional - Longitude, required if `$lat` is a string.

### Returns
- **string** - The county name, or `''` if not found.

### Example
```php
$county = MapsHelper::getCountyFromLatLng([39.5, -107.7]);
```
```

--------------------------------

### Define Map Table Filters and Actions

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/README.md

Shows how to implement MapIsFilter and GoToAction within a MapTableWidget.

```php
    protected function getTableFilters(): array
    {
        return [
            MapIsFilter::make('map'),
        ];
    }

    protected function getTableActions(): array
    {
        return [
            GoToAction::make()
                ->zoom(14),
        ];
    }
```

--------------------------------

### RadiusFilter::setUp method signature

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/filters.md

Sets the column span and registers the indicating closure.

```php
protected function setUp(): void
```

--------------------------------

### polyOptions, rectangleOptions, circleOptions signatures

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/fields-map.md

Method signatures for setting styling options for the poly, rectangle, and circle drawing overlays. Getters getPolyOptions(), getRectangleOptions(), and getCircleOptions() are available.

```php
public function polyOptions(Closure|array $polyOptions): static
public function rectangleOptions(Closure|array $rectangleOptions): static
public function circleOptions(Closure|array $circleOptions): static
```

--------------------------------

### minChars method signature

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/fields-geocomplete.md

Minimum characters typed before autocomplete starts searching. Default is 0; README recommends 3.

```php
public function minChars(int $minChars): static
```

--------------------------------

### Geocoder Diagnostic Methods

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/geocoder.md

Diagnostic methods for reverse geocoding, including testReverse and testReverseModel, with parameters, return values, and usage examples.

```APIDOC
## testReverse

### Description
Performs a reverse geocoding lookup for a given point (latitude/longitude) and returns formatted address components for every symbol in `$symbolComponents`. Returns an empty array when the reverse query has no result.

### Method
`testReverse`

### Signature
```php
public function testReverse(array|string $lat, ?string $lng = null, $withComponents = false): array
```

### Parameters
- `$lat` (array|string) - Required - Point array or latitude
- `$lng` (?string) - Optional - Longitude when `$lat` is scalar
- `$withComponents` (bool) - Optional - Append the Google address-component key as a third element

### Returns
Returns rows of `[$symbol, $formattedValue]` (or `[symbol, value, component]`) for every symbol in `$symbolComponents`, `[]` when the reverse query has no result.

### Source
`src/Helpers/Geocoder.php:329`

## testReverseModel

### Description
Runs `testReverse()` against a model record's lat/lng fields. Returns an empty array when the record is missing.

### Method
`testReverseModel`

### Signature
```php
public function testReverseModel(string $model, $id, $latField, $lngField): array
```

### Parameters
- `$model` (string) - Required - Model class name
- `$id` (mixed) - Required - Record identifier
- `$latField` (string) - Required - Latitude field name
- `$lngField` (string) - Required - Longitude field name

### Returns
Returns the result of `testReverse()` for the model record's lat/lng; `[]` when the record is missing.

### Source
`src/Helpers/Geocoder.php:348`

### Example
```php
$formats = $geocoder->testReverse(38.8976633, -77.0365739, true);

foreach ($formats as [$symbol, $value, $component]) {
    // '%n' => '1600', component 'street_number'
}
```
```

--------------------------------

### mount

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/widgets.md

Initializes the widget's data checksum to an empty JSON object so the first map data update always detects a change.

```APIDOC
## mount

### Description
Initializes `$this->dataChecksum = md5('{}')` so the first `updateMapData()` always detects a change.

### Method
mount

### Signature
```php
public function mount()
```

### Source
`src/Widgets/MapWidget.php:75`

```

--------------------------------

### InteractsWithMaps trait usage example

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/helpers.md

Demonstrates how to use the InteractsWithMaps trait in an EditRecord Livewire component. Required for reverseGeocodeUsing() and placeUpdatedUsing() callbacks to work.

```php
use Cheesegrits\FilamentGoogleMaps\Concerns\InteractsWithMaps;

class EditLocation extends EditRecord
{
    use InteractsWithMaps;

    // Provide reverseGeocodeUsing / placeUpdatedUsing callbacks on your
    // Map / Geocomplete fields; the trait receives their browser events.
}
```

--------------------------------

### Import MapColumn

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/columns-map-column.md

Import the MapColumn class from the Cheesegrits\FilamentGoogleMaps\Columns namespace.

```php
use Cheesegrits\FilamentGoogleMaps\Columns\MapColumn;
```

--------------------------------

### MapIsFilter usage in getTableFilters

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/filters.md

Usage example for adding the MapIsFilter to a table's filters. Import the filter class and add it to the getTableFilters method.

```php
use Cheesegrits\FilamentGoogleMaps\Filters\MapIsFilter;

protected function getTableFilters(): array
{
    return [
        // ... other filters
        MapIsFilter::make('map'),
    ];
}
```

--------------------------------

### hasJs / jsUrl / hasCss / cssUrl

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/widgets.md

Methods for asset loading. `hasJs()` indicates a JS bundle exists, `jsUrl()` returns its URL, `hasCss()` indicates whether a CSS bundle exists, and `cssUrl()` resolves the CSS bundle URL.

```APIDOC
## hasJs

### Description
Returns `true`.

### Method
hasJs

### Signature
```php
public function hasJs(): bool
```

### Returns
- **bool** - Always `true`.

### Source
`src/Widgets/MapWidget.php:214`

---

## jsUrl

### Description
Reads `dist/mix-manifest.json` and returns the URL of the widget JS bundle.

### Method
jsUrl

### Signature
```php
public function jsUrl(): string
```

### Returns
- **string** - The URL of the JS bundle.

### Source
`src/Widgets/MapWidget.php:219`

---

## hasCss

### Description
Returns `false`.

### Method
hasCss

### Signature
```php
public function hasCss(): bool
```

### Returns
- **bool** - Always `false`.

### Source
`src/Widgets/MapWidget.php:226`

---

## cssUrl

### Description
Resolves the (unused) CSS bundle URL.

### Method
cssUrl

### Signature
```php
public function cssUrl(): string
```

### Returns
- **string** - The URL of the CSS bundle.

### Source
`src/Widgets/MapWidget.php:231`

```

--------------------------------

### FieldHelper::getFieldId usage example

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/helpers.md

Shows how to retrieve the DOM element ID of a named field relative to a component. Returns null when the field is not on the same form. Used internally by Map::getAutocompleteId().

```php
$id = FieldHelper::getFieldId('airport_name', $mapComponent);
// null when the field isn't on the same form
```

--------------------------------

### getHeading and getFilters stubs

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/_autodocs/api-reference/fields-widget-map.md

Stubs for widget compatibility: getHeading returns the literal string 'get heading here' and getFilters returns []. These are scaffolding and not used by the map display. Sources: src/Fields/WidgetMap.php:65, :70.

```php
public function getHeading(): string
public function getFilters(): array
```

--------------------------------

### Artisan Command for Map Widget Creation

Source: https://github.com/cheesegrits/filament-google-maps/blob/v3/README.md

Run the fgm:make-widget command to generate a map widget, specifying the type, name, model, and resource.

```shell
php artisan fgm:make-widget


 Widget type (just a map, or map with integrated table [Map]:
  [0] Map
  [1] Map & Table
 > 1

 Name (e.g. `DealershipMap`):
 > LocationMapTableWidget

 Model (e.g. `Location` or `Maps/Dealership`):
 > Location

 (Optional) Resource (e.g. `LocationResource`):
 > LocationResource

Successfully created the LocationMapTableWidget in your LocationResource resource class.

Make sure to register the widget both in `LocationResource::getWidgets()`,
and in either `getHeaderWidgets()` or `getFooterWidgets()` of any `LocationResource` page.
```
Tokens:
Raw