{"id":18716554,"url":"https://github.com/dotswan/filament-map-picker","last_synced_at":"2025-12-13T01:55:37.620Z","repository":{"id":196637414,"uuid":"696807825","full_name":"dotswan/filament-map-picker","owner":"dotswan","description":"Map Picker is a Filament custom field designed to simplify the process of choosing a location on a map and obtaining its geo-coordinates.","archived":false,"fork":false,"pushed_at":"2025-12-01T05:40:02.000Z","size":3100,"stargazers_count":119,"open_issues_count":12,"forks_count":33,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-12-03T16:49:21.479Z","etag":null,"topics":["filament","filamentphp","geo-man","geoman","laravel","leaflet","leafletjs","map","map-picker","openstreetmap","osm","php"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dotswan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-09-26T13:22:15.000Z","updated_at":"2025-12-01T05:39:34.000Z","dependencies_parsed_at":"2024-03-23T12:21:15.046Z","dependency_job_id":"61267f7a-cbab-40f5-ae26-18432069ae54","html_url":"https://github.com/dotswan/filament-map-picker","commit_stats":{"total_commits":47,"total_committers":5,"mean_commits":9.4,"dds":0.3829787234042553,"last_synced_commit":"285158a99a09f3dc92c87fdf1bf5231e4396575a"},"previous_names":["dotswan/map-picker","dotswan/filament-map-picker"],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/dotswan/filament-map-picker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotswan%2Ffilament-map-picker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotswan%2Ffilament-map-picker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotswan%2Ffilament-map-picker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotswan%2Ffilament-map-picker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dotswan","download_url":"https://codeload.github.com/dotswan/filament-map-picker/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotswan%2Ffilament-map-picker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27698094,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-12T02:00:06.775Z","response_time":129,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["filament","filamentphp","geo-man","geoman","laravel","leaflet","leafletjs","map","map-picker","openstreetmap","osm","php"],"created_at":"2024-11-07T13:13:04.152Z","updated_at":"2025-12-13T01:55:37.600Z","avatar_url":"https://github.com/dotswan.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Filament V3 Map Picker\n\n[![Latest Version on Packagist][ico-version]][link-packagist]\n[![Total Downloads][ico-downloads]][link-downloads]\n[![Software License][ico-license]][link-license]\n\n\nA custom field for Filament that allows you to effortlessly select a location on a map and retrieve geographical coordinates.\n\n\n![270298161-46b97f72-518b-40c5-963b-8e9d39d77d67](https://github.com/dotswan/map-picker/assets/20874565/a5dbda7b-b5c1-4038-9bf9-7a0a4c8ff632)\n\n![image](https://github.com/user-attachments/assets/53d9de27-7e1f-4638-8c71-3b2c6b5d68ef)\n\n## Introduction\n\nMap Picker is a Filament custom field designed to simplify the process of choosing a location on a map and obtaining its geo-coordinates.\n\n* Features include:\n   * A Field for Filament-v3 with OpenStreetMap Integration\n   * Receive Real-time Coordinates Upon Marker Movement Completion\n   * Tailor Controls and Marker Appearance to Your Preferences\n   * GeoMan Integration for Advanced Map Editing Capabilities\n\n* Latest versions of PHP and Filament\n* Best practices applied:\n  * [`README.md`][link-readme] (badges included)\n  * [`LICENSE`][link-license]\n  * [`composer.json`][link-composer-json]\n  * [`.gitignore`][link-gitignore]\n  * [`pint.json`][link-pint]\n\n\n## GeoMan Integration\n\nThis package now includes integration with GeoMan, a powerful tool for creating and editing geometries on maps. GeoMan allows users to draw various shapes, edit existing geometries, and perform advanced map editing tasks.\n\n### GeoMan Features:\n\n- Draw markers, polygons, polylines, and circles\n- Edit existing geometries\n- Cut polygons\n- Rotate shapes\n- Drag mode for easy shape manipulation\n- Delete layers\n\n## Supported Maps\n\nMap Picker currently supports the following map:\n\n1. Open Street Map (OSM)\n\nAdditional map options will be added to the package as needed and tested.\n\n## Installation\n\nYou can easily install the package via Composer:\n\n```bash\ncomposer require dotswan/filament-map-picker\n```\n\n## Basic Usage\n\nResource file:\n\n```php\n\u003c?php\nnamespace App\\Filament\\Resources;\nuse Filament\\Resources\\Resource;\nuse Filament\\Resources\\Forms\\Form;\nuse Dotswan\\MapPicker\\Fields\\Map;\n...\n\nclass FilamentResource extends Resource\n{\n    ...\n    public static function form(Form $form)\n    {\n        return $form-\u003eschema([\n            Map::make('location')\n                -\u003elabel('Location')\n                -\u003ecolumnSpanFull()\n                // Basic Configuration\n                -\u003edefaultLocation(latitude: 40.4168, longitude: -3.7038)\n                -\u003edraggable(true)\n                -\u003eclickable(true) // click to move marker\n                -\u003ezoom(15)\n                -\u003eminZoom(0)\n                -\u003emaxZoom(28)\n                -\u003etilesUrl(\"https://tile.openstreetmap.de/{z}/{x}/{y}.png\")\n                -\u003edetectRetina(true)\n                \n                // Marker Configuration\n                -\u003eshowMarker(true)\n                -\u003emarkerColor(\"#3b82f6\")\n                -\u003emarkerHtml('\u003cdiv class=\"custom-marker\"\u003e...\u003c/div\u003e')\n                -\u003emarkerIconUrl('/path/to/marker.png')\n                -\u003emarkerIconSize([36, 36])\n                -\u003emarkerIconClassName('my-marker-class')\n                -\u003emarkerIconAnchor([18, 36])\n                \n                // Controls\n                -\u003eshowFullscreenControl(true)\n                -\u003eshowZoomControl(true)\n                \n                // Location Features\n                -\u003eliveLocation(true, true, 5000)\n                -\u003eshowMyLocationButton(true)\n                -\u003eboundaries(true, 49.5, -11, 61, 2) // Example for British Isles\n                -\u003erangeSelectField('distance')\n                \n                // GeoMan Integration\n                -\u003egeoMan(true)\n                -\u003egeoManEditable(true)\n                -\u003egeoManPosition('topleft')\n                -\u003edrawCircleMarker(true)\n                -\u003erotateMode(true)\n                -\u003edrawMarker(true)\n                -\u003edrawPolygon(true)\n                -\u003edrawPolyline(true)\n                -\u003edrawCircle(true)\n                -\u003edrawRectangle(true)\n                -\u003edrawText(true)\n                -\u003edragMode(true)\n                -\u003ecutPolygon(true)\n                -\u003eeditPolygon(true)\n                -\u003edeleteLayer(true)\n                -\u003esetColor('#3388ff')\n                -\u003esetFilledColor('#cad9ec')\n                -\u003esnappable(true, 20)\n                \n                // Extra Customization\n                -\u003eextraStyles([\n                    'min-height: 150vh',\n                    'border-radius: 50px'\n                ])\n                -\u003eextraControl(['customControl' =\u003e true])\n                -\u003eextraTileControl(['customTileOption' =\u003e 'value'])\n                \n                // State Management\n                -\u003eafterStateUpdated(function (Set $set, ?array $state): void {\n                    $set('latitude', $state['lat']);\n                    $set('longitude', $state['lng']);\n                    $set('geojson', json_encode($state['geojson']));\n                })\n                -\u003eafterStateHydrated(function ($state, $record, Set $set): void {\n                    $set('location', [\n                        'lat' =\u003e $record-\u003elatitude,\n                        'lng' =\u003e $record-\u003elongitude,\n                        'geojson' =\u003e json_decode(strip_tags($record-\u003edescription))\n                    ]);\n                })\n        ]);\n    }\n    ...\n}\n```\n\nIf you wish to update the map location and marker either through an action or after altering other input values, you can trigger a refresh of the map using the following approach:\n\n```php\n\nuse Filament\\Forms\\Components\\Actions\\Action;\nuse Filament\\Forms\\Components\\Actions;\nuse Filament\\Support\\Enums\\VerticalAlignment;\n\nActions::make([\n    Action::make('Set Default Location')\n        -\u003eicon('heroicon-m-map-pin')\n        -\u003eaction(function (Set $set, $state, $livewire): void {\n            $set('location', ['lat' =\u003e '52.35510989541003', 'lng' =\u003e '4.883422851562501']);\n            $set('latitude', '52.35510989541003');\n            $set('longitude', '4.883422851562501');\n            $livewire-\u003edispatch('refreshMap');\n        })\n])-\u003everticalAlignment(VerticalAlignment::Start);\n\n```\n\n### clickable Option\n\nThis will allow you to set the point on the map with a click. Default behaviour has the marker centered as the map is\ndragged underneath. You could, with this, keep the map still and lock the zoom and choose to click to place the marker.\n\n```php\nMap::make('location')\n  -\u003edefaultLocation(latitude: 40.4168, longitude: -3.7038)\n  -\u003eshowMarker(true)\n  -\u003eclickable(true)\n  -\u003etilesUrl(\"https://tile.openstreetmap.de/{z}/{x}/{y}.png\")\n  -\u003ezoom(12)\n```\n\n\n### rangeSelectField Option\n\nThe rangeSelectField Option allows you to specify another field on your form which specifies a range from the point\nidentified by the marker.  That field must be in meters. So for example you could do this:\n\n```php\nFieldset::make('Location')\n    -\u003eschema([\n        Select::make('membership_distance')\n            -\u003eenum(MembershipDistance::class)\n            -\u003eoptions(MembershipDistance::class)\n            -\u003erequired(),\n\n        Map::make('location')\n            -\u003edefaultLocation(latitude: 40.4168, longitude: -3.7038)\n            -\u003eshowMarker(true)\n            -\u003eshowFullscreenControl(false)\n            -\u003eshowZoomControl()\n            -\u003etilesUrl(\"https://tile.openstreetmap.de/{z}/{x}/{y}.png\")\n            -\u003ezoom(12)\n            -\u003edetectRetina()\n            -\u003erangeSelectField('membership_distance')\n            -\u003esetFilledColor('#cad9ec'),\n    ])\n    -\u003ecolumns(1),\n```\n\nIn this case, as you change the value on the Select a circle of that radius centered on the marker will\nchange to match your drop down.\n\n\n#### `liveLocation` Option\n\nThe `liveLocation` method accepts three parameters:\n\n1. **`bool $send`:** Determines if the user's live location should be sent.\n2. **`bool $realtime`:** Controls whether the live location should be sent to the server periodically.\n3. **`int $milliseconds`:** Sets the interval (in milliseconds) at which the user's location is updated and sent to the server.\n\nExample:\n\n```php\nMap::make('location')\n    -\u003eliveLocation(true, true, 10000)  // Updates live location every 10 seconds\n    -\u003eshowMarker()\n    -\u003edraggable()\n```\n\n### boundaries Option\n\nThe idea here is that you can set a boundary box by defining two points, the southwest most point and the north east\nmost point, and your map will pan back into the panned area if you drag away, such that the points can only be selected\nif you stay in the map.\n\nYou will want to set the minZoom() along with this if you set showZoomControl(true). To choose a good value for minZoom()\nyou will need to consider both the size of the map on the screen and the size of the bounding boxm, and you may find trial and\nerror is the best method.\n\n```php\nMap::make('location')\n    -\u003eshowMarker()\n    -\u003eboundaries(true,49,11.1,61.0,2.1)\n    -\u003edraggable()\n```\n\nTo turn it off again - possibly a strange use case - `boundaries(false)` is what you want.\n\n\n### setBoundsToBritishIsles Option\n\nThis is a convenience function that uses the boundaries option above, setting the boundary box to\n(49.5,-11) and (61,2)\n\n\n## Options Table\n\nHere's a table describing all available options and their default values:\n\n| Option | Description | Default Value |\n|--------|-------------|---------------|\n| statePath | Path to the state | '' |\n| draggable | Allow map dragging | true |\n| showMarker | Display marker on the map | true |\n| tilesUrl | URL for map tiles | 'http://tile.openstreetmap.org/{z}/{x}/{y}.png' |\n| attribution | Map attribution text | null |\n| zoomOffset | Zoom offset | -1 |\n| tileSize | Tile size | 512 |\n| detectRetina | Detect and use retina tiles | true |\n| rangeSelectField | Field name for range selection | 'distance' |\n| minZoom | Minimum zoom level | 0 |\n| maxZoom | Maximum zoom level | 28 |\n| zoom | Default zoom level | 15 |\n| clickable | Allow clicking to place marker | false |\n| markerColor | Color of the marker | '#3b82f6' |\n| liveLocation | Enable live location updates | false |\n| bounds | Enable map boundaries | false |\n| showMyLocationButton | Show \"My Location\" button settings | [false, false, 5000] |\n| default | Default location coordinates | ['lat' =\u003e 0, 'lng' =\u003e 0] |\n| markerHtml | Custom HTML for marker | '' |\n| markerIconUrl | URL for custom marker icon | null |\n| markerIconSize | Size of marker icon | [36, 36] |\n| markerIconClassName | CSS class for marker icon | '' |\n| markerIconAnchor | Anchor point for marker icon | [18, 36] |\n| geoMan.show | Enable GeoMan | false |\n| geoMan.editable | Allow editing with GeoMan | true |\n| geoMan.position | Position of GeoMan controls | 'topleft' |\n| geoMan.drawCircleMarker | Allow drawing circle markers | true |\n| geoMan.rotateMode | Enable rotate mode | true |\n| geoMan.drawMarker | Allow drawing markers | true |\n| geoMan.drawPolygon | Allow drawing polygons | true |\n| geoMan.drawPolyline | Allow drawing polylines | true |\n| geoMan.drawCircle | Allow drawing circles | true |\n| geoMan.dragMode | Enable drag mode | true |\n| geoMan.cutPolygon | Allow cutting polygons | true |\n| geoMan.editPolygon | Allow editing polygons | true |\n| geoMan.deleteLayer | Allow deleting layers | true |\n| geoMan.color | Stroke color for drawings | '#3388ff' |\n| geoMan.filledColor | Fill color for drawings | '#cad9ec' |\n| geoMan.snappable | Enable snapping to objects | false |\n| geoMan.snapDistance | Distance for snapping | 20 |\n| geoMan.drawText | Allow drawing text | true |\n| geoMan.drawRectangle | Allow drawing rectangles | true |\n\n### Usage As Infolist Field\n\nThe MapEntry Infolist field displays a map with all the same configuration options available in the form field. Here's an example:\n\n```php\nuse Dotswan\\MapPicker\\Infolists\\MapEntry;\n\npublic static function infolist(Infolist $infolist): Infolist\n{\n    return $infolist\n        -\u003eschema([\n            MapEntry::make('location')\n                // Basic Configuration\n                -\u003edefaultLocation(latitude: 40.4168, longitude: -3.7038)\n                -\u003edraggable(false) // Usually false for infolist view\n                -\u003ezoom(15)\n                -\u003eminZoom(0)\n                -\u003emaxZoom(28)\n                -\u003etilesUrl(\"https://tile.openstreetmap.de/{z}/{x}/{y}.png\")\n                -\u003edetectRetina(true)\n                \n                // Marker Configuration\n                -\u003eshowMarker(true)\n                -\u003emarkerColor(\"#22c55eff\")\n                -\u003emarkerHtml('\u003cdiv class=\"custom-marker\"\u003e...\u003c/div\u003e')\n                -\u003emarkerIconUrl('/path/to/marker.png')\n                -\u003emarkerIconSize([36, 36])\n                -\u003emarkerIconClassName('my-marker-class')\n                -\u003emarkerIconAnchor([18, 36])\n                \n                // Controls\n                -\u003eshowFullscreenControl(true)\n                -\u003eshowZoomControl(true)\n                \n                // GeoMan Integration (if needed for viewing)\n                -\u003egeoMan(true)\n                -\u003egeoManEditable(false) // Usually false for infolist view\n                -\u003egeoManPosition('topleft')\n                -\u003edrawCircleMarker(true)\n                -\u003edrawMarker(true)\n                -\u003edrawPolygon(true)\n                -\u003edrawPolyline(true)\n                -\u003edrawCircle(true)\n                -\u003edrawRectangle(true)\n                -\u003edrawText(true)\n                \n                // Styling\n                -\u003eextraStyles([\n                    'min-height: 50vh',\n                    'border-radius: 50px'\n                ])\n                \n                // State Management\n                -\u003estate(fn ($record) =\u003e [\n                    'lat' =\u003e $record?-\u003elatitude,\n                    'lng' =\u003e $record?-\u003elongitude,\n                    'geojson' =\u003e $record?-\u003egeojson ? json_decode($record-\u003egeojson) : null\n                ])\n        ]);\n}\n```\n\nNote: In infolist context, it's common to:\n- Set `draggable(false)` since it's typically used for viewing only\n- Set `geoManEditable(false)` if GeoMan is enabled\n- Use `state()` instead of `afterStateHydrated()`/`afterStateUpdated()`\n- Adjust the height to be smaller than in forms (e.g., 50vh vs 150vh)\n\n## Usage Guide for Handling Map Locations\n\nThis section explains how to handle and display map locations within your application using this package.\n\n**Step 1: Define Your Database Schema**\n\nEnsure your database table includes latitude and longitude columns.\nThis is essential for storing the coordinates of your locations. You can define your table schema as follows:\n\n```php\n$table-\u003edouble('latitude')-\u003enullable();\n$table-\u003edouble('longitude')-\u003enullable();\n```\n\n**Step 2: Retrieve and Set Coordinates**\n\nWhen loading a record, ensure you correctly retrieve and set the latitude and longitude values.\nUse the following method within your form component:\n\n```php\n-\u003eafterStateHydrated(function ($state, $record, Set $set): void {\n    $set('location', ['lat' =\u003e $record?-\u003elatitude, 'lng' =\u003e $record?-\u003elongitude]);\n})\n```\n\n**Step 3: Add Form Fields for Latitude and Longitude**\n\nAdd hidden form fields for latitude and longitude to your form. This ensures the values are present but not visible to the user:\n\n```php\nTextInput::make('latitude')\n    -\u003ehiddenLabel()\n    -\u003ehidden(),\n\nTextInput::make('longitude')\n    -\u003ehiddenLabel()\n    -\u003ehidden()\n```\n\nIf you prefer to display these values in a read-only format, replace `hidden()` with `readOnly()`.\n\n### Alternative Approach: Using a Single Location Attribute\n\nIf you prefer to handle the location as a single field, you can define a custom attribute in your model. This method avoids the need for separate latitude and longitude columns:\n\n```php\nclass YourModel extends Model\n{\n    protected function location(): Attribute\n    {\n        return Attribute::make(\n            get: fn (mixed $value, array $attributes) =\u003e [\n                'latitude' =\u003e $attributes['latitude'],\n                'longitude' =\u003e $attributes['longitude']\n            ],\n            set: fn (array $value) =\u003e [\n                'latitude' =\u003e $value['latitude'],\n                'longitude' =\u003e $value['longitude']\n            ],\n        );\n    }\n}\n```\n\nThis approach encapsulates both latitude and longitude within a single location attribute, streamlining your code.\n\n\n\n## License\n\n[MIT License](LICENSE.md) © Dotswan\n\n## Security\n\nWe take security seriously. If you discover any bugs or security issues, please help us maintain a secure project by reporting them through our [`GitHub issue tracker`][link-github-issue]. You can also contact us directly at [tech@dotswan.com](mailto:tech@dotswan.com).\n\n## Contribution\n\nWe welcome contributions! contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.\n\nIf you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag \"enhancement\". Don't forget to give the project a star! Thanks again!\n\n1. Fork the Project\n2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the Branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n\n[ico-version]: https://img.shields.io/packagist/v/dotswan/filament-map-picker.svg?style=flat-square\n[ico-license]: https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square\n[ico-downloads]: https://img.shields.io/packagist/dt/dotswan/filament-map-picker.svg?style=flat-square\n\n[link-workflow-test]: https://github.com/dotswan/filament-map-picker/actions/workflows/ci.yml\n[link-packagist]: https://packagist.org/packages/dotswan/filament-map-picker\n[link-license]: https://github.com/dotswan/filament-map-picker/blob/master/LICENSE.md\n[link-downloads]: https://packagist.org/packages/dotswan/filament-map-picker\n[link-readme]: https://github.com/dotswan/filament-map-picker/blob/master/README.md\n[link-github-issue]: https://github.com/dotswan/filament-map-picker/issues\n[link-docs]: https://github.com/dotswan/filament-map-picker/blob/master/docs/openapi.yaml\n[link-composer-json]: https://github.com/dotswan/filament-map-picker/blob/master/composer.json\n[link-gitignore]: https://github.com/dotswan/filament-map-picker/blob/master/.gitignore\n[link-pint]: https://github.com/dotswan/filament-map-picker/blob/master/pint.json\n[link-author]: https://github.com/dotswan\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotswan%2Ffilament-map-picker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdotswan%2Ffilament-map-picker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotswan%2Ffilament-map-picker/lists"}