README

Using this package, you can use spatial fields in Laravel Nova.

nova-map-field.mp4

I am on an open-source journey 🚀, and I wish I could solely focus on my development path without worrying about my financial situation. However, as life is not perfect, I have to consider other factors.

Therefore, if you decide to use my packages, please kindly consider making a donation. Any amount, no matter how small, goes a long way and is greatly appreciated. 🍺

Requirements:

PHP 8.1 or higher
Laravel 10.* or higher

Laravel Compatibility

Laravel	PHP	Nova Map Field
^8.0 - ^9.0	^8.0.2	^3.0
^10.0 - ^11.0	^8.1	^4.0 (latest)

Installation

Install the package via composer:

composer require mostafaznv/nova-map-field

Publish config and assets:

php artisan vendor:publish --provider="Mostafaznv\NovaMapField\NovaMapFieldServiceProvider"

Done

Usage

Create table with spatial fields

<?php

return new class extends Migration
{
    public function up()
    {
        Schema::create('locations', function (Blueprint $table) {
            $table->id();
            $table->string('title', 150);
            
            # laravel 10
            $table->point('location')->nullable();
            $table->polygon('area')->nullable();
            $table->multiPolygon('areas')->nullable();
            
            # laravel 11 and higher
            $table->geometry('location', subtype: 'point')->nullable();
            $table->geometry('area', subtype: 'polygon')->nullable();
            $table->geometry('areas', subtype: 'multipolygon')->nullable();

            $table->timestamps();
        });
    }
};

Add `HasSpatial` trait to model

<?php

namespace App\Models;

use MatanYadaev\EloquentSpatial\Traits\HasSpatial;


class Location extends Model
{
    use HasSpatial;
}

Define spatial columns of model

<?php

namespace App\Models;

use MatanYadaev\EloquentSpatial\Objects\MultiPolygon;
use MatanYadaev\EloquentSpatial\Objects\Point;
use MatanYadaev\EloquentSpatial\Objects\Polygon;
use MatanYadaev\EloquentSpatial\Traits\HasSpatial;


class Location extends Model
{
    use HasSpatial;

    protected $casts = [
        'location' => Point::class,
        'area'     => Polygon::class,
        'areas'    => MultiPolygon::class
    ];
}

Add map fields to resource

<?php

namespace App\Nova\Resources;

use Mostafaznv\NovaMapField\Fields\MapMultiPolygonField;
use Mostafaznv\NovaMapField\Fields\MapPointField;
use Mostafaznv\NovaMapField\Fields\MapPolygonField;


class Location extends Resource
{
    public function fields(Request $request): array
    {
        return [
            MapPointField::make('location'),
            MapPolygonField::make('area'),
            MapMultiPolygonField::make('areas'),
        ];
    }
}

Done

Map Field Methods

method	Arguments	description
templateUrl	url `string`	Specifies template of map
projection	projection `string`	Specifies projection of map
srid	srid `integer` `default: 0`	Specifies SRID of map
defaultLatitude	latitude `float`	Specifies latitude of map on page load
defaultLongitude	longitude `float`	Specifies longitude of map on page load
zoom	zoom `integer`	Specifies default map zoom
withoutZoomControl	status `bool` `default: true`	Specifies whether zoom in/out button should display on map or not
withoutZoomSlider	status `bool` `default: true`	Specifies whether zoom slider should display on map or not
withFullScreenControl	status `bool` `default: true`	Specifies whether full screen button should display on map or not
mapHeight	height `integer` `default: 400`	Map's height
hideDetailButton	status `bool` `default: true`	Specifies whether Show Details button should appear on detail pages or not
markerIcon	icon `integer` `available: 1, 2, 3`	Marker icon
withSearchBox	`boolean`	Specifies whether map has search box or not
searchProvider	provider `MapSearchProvider`
searchProviderApiKey	apiKey `string`	Specifies api key for search provider, if needed
withAutocompleteSearch	status `bool` `default: true`	Specifies whether search results should load immediately or not
searchAutocompleteMinLength	minLength `int`	Specifies the minimum number of characters to trigger search action
searchAutocompleteTimeout	timeout `int`	Specifies the minimum number of ms to wait before triggering search action
searchLanguage	language `string`	Specifies preferable language
searchPlaceholder	placeholder `string`
searchBoxType	type `MapSearchBoxType`	Using this item, you can specify type of search box (button, or text-field
searchResultLimit	limit `int`	Specifies limit of results
searchResultKeepOpen	status `boolean`	Specifies whether the results keep opened
withTransformation	status `boolean`	Specifies whether transport feature should be enable on polygons
transformScale	status `boolean`	Using this method, you can enable/disable scaling features
transformRotate	status `boolean`	Using this method, you can enable/disable rotating features
transformStretch	status `boolean`	Using this method, you can enable/disable stretch option
requiredOnCreate	status `bool` `default: true`	Makes field required on creation
requiredOnUpdate	status `bool` `default: true`	Makes field required on update
default	$callback `PointValue`	Set default value for map field. Note: Only works in `MapPointField`
capture	capture `Capture` `experimental`	By employing this method, you can capture a screenshot reflecting the current state of the map field and save it to the filesystem

Config Properties

Method	Type	Default	Description
template-url	string	`https://{a-c}.tile.openstreetmap.org/{z}/{x}/{y}.png`	Default Template URL. Must include `{x}`, `{y}` or `{-y}`, and `{z}` placeholders.
projection	string	`EPSG:3857`	Default projection of map
srid	int	0	Default SRID of map
default-latitude	bool	0	Default latitude of map
default-longitude	bool	0	Default longitude of map
zoom	int	12	Default zoom of map
controls.zoom-control	bool	true	Specifies if map should display zoom controls (zoom in/out buttons) or not
controls.zoom-slider	bool	true	Specifies if map should display zoom slider or not
controls.full-screen-control	bool	false	Specifies if map should display full screen button or not
controls.undo-control	bool	true	Specifies if map should display undo control or not (Only for `Polygon` and `MultiPolygon`)
controls.clear-map-control	bool	true	Specifies if map should display clear map control or not (Only for `Polygon` and `MultiPolygon`)
map-height	int	400	Specifies map height
icon	int	1	Specifies marker icon. available values: `1, 2, 3`
style.stroke-color	string	red	Using this property, you can specify stroke color of polygons or other shapes. Either in hexadecimal or as RGBA array
style.stroke-width	int	2	Width of the stroke (px)
style.fill-color	string	rgba(255, 0, 0, 0.4)	Using this property, you can specify filling color of polygons or other shapes. Either in hexadecimal or as RGBA array.
show-detail-button	bool	true	Specifies whether Show Details button should appear on detail pages or not
search.enable	bool	true	Using this item, you can toggle displaying search box on maps
search.provider	MapSearchProvider	OSM	Specifies search provider available providers: `OSM, MAPQUEST, PHOTON, PELIAS, BING, OPENCAGE`
search.api-key	string	''	Specifies API key if required
search.autocomplete	bool	false	Using this item, you can toggle autocomplete feature for search box
search.autocomplete-min-length	int	2	The minimum number of characters to trigger search
search.autocomplete-timeout	int	200	The minimum number of ms to wait before triggering search action
search.language	string	en-US	Specifies preferable language
search.placeholder	string	Search for an address	Specifies placeholder for text input
search.box-type	MapSearchBoxType	TEXT_FIELD	Specifies type of search box. available types: `BUTTON, TEXT_FIELD`
search.limit	int	5	Specifies limit of results
search.keep-open	bool	false	Specifies whether the results keep opened
transform.enable	bool	true	Using this item, you can toggle transforming polygons maps
transform.scale	bool	true	Using this property, you can toggle scaling features
transform.scale	bool	true	Using this property, you can toggle rotating features
transform.stretch	bool	true	Using this property, you can enable/disable stretch option

Capture Screenshot

Utilizing this method enables the capture of a screenshot that mirrors the current state of the map field, subsequently saving it to the filesystem. It is important to note that this feature is experimental and its performance may vary. The underlying mechanism operates by generating an image on the client's machine each time the client/admin modifies the map field state. Subsequently, this image is transmitted to the server, where it is then stored in the filesystem.

To enable this feature, you must first add the capture method to your map field. This method accepts a single argument, which is an instance of the Capture class.

<?php

namespace App\Nova\Resources;

use App\Nova\Resource;
use Illuminate\Http\Request;
use Laravel\Nova\Fields\ID;
use Laravel\Nova\Fields\Image;
use App\Models\Location as Model;
use Mostafaznv\NovaMapField\DTOs\Capture;
use Mostafaznv\NovaMapField\Fields\MapPointField;

class Location extends Resource
{
    public static string $model = Model::class;

    public function fields(Request $request): array
    {
        return [
            ID::make()->sortable(),

            MapPointField::make(trans('Location'), 'location')
                ->capture(
                     Capture::make('location_screenshot', 600, 600)
                        ->disk('location')
                        ->maxZoom(9)
                        ->padding([10, 10, 10, 10])
                        ->nearest(true)
                        ->prunable(true)
                ),

            Image::make(trans('Location Screenshot'), 'location_screenshot')
                ->disk('location')
                ->prunable()
                ->exceptOnForms(),
        ];
    }
}

Note

Activating this feature is as straightforward as calling the static make function of Capture. Nevertheless, for those seeking to tailor the behavior of this functionality, alternative methods are available for customization.

Using Spatial Columns over Application

This package uses Laravel Eloquent Spatial under the hood. to use columns and querying them over the application, please read Laravel Eloquent Spatial documentation

Tricks

Transform Polygons

To transform polygons, You should press Alt (Option ⌥) button and drag that polygon everywhere you want.

Select Polygons

To select polygons (and modify them), You can press Alt (Option ⌥) button and then click on the polygon. By pressing the Alt (Option ⌥) key, drawing mode will be disabled, and you can select every polygon you want.

Complete Example

<?php

namespace App\Nova\Resources;

use App\Nova\Resource;
use Illuminate\Http\Request;
use Laravel\Nova\Fields\ID;
use Laravel\Nova\Fields\Text;
use App\Models\Location as Model;
use Mostafaznv\NovaMapField\DTOs\Capture;
use Mostafaznv\NovaMapField\DTOs\PointValue;
use Mostafaznv\NovaMapField\Enums\MapSearchBoxType;
use Mostafaznv\NovaMapField\Enums\MapSearchProvider;
use Mostafaznv\NovaMapField\Fields\MapPointField;

class Location extends Resource
{
    public static string $model = Model::class;

    public function fields(Request $request): array
    {
        return [
            ID::make()->sortable(),

            Text::make('Title')
                ->sortable()
                ->rules('required', 'max:255'),
                
            MapPointField::make(trans('Location'), 'location')
                ->templateUrl('https://{a-c}.tile.openstreetmap.org/{z}/{x}/{y}.png')
                ->projection('EPSG:3857')
                ->srid(3857)
                ->defaultLatitude(35.6978527)
                ->defaultLongitude(51.4037269)
                ->zoom(14)
                ->withoutZoomControl()
                ->withoutZoomSlider()
                ->withoutUndoControl()
                ->withFullScreenControl()
                ->mapHeight(360)
                ->hideDetailButton(false)
                ->markerIcon(3)
                ->searchProvider(MapSearchProvider::OSM)
                ->searchProviderApiKey('api-key')
                ->withAutocompleteSearch()
                ->searchAutocompleteMinLength(4)
                ->searchAutocompleteTimeout(500)
                ->searchLanguage('fa-IR')
                ->searchPlaceholder('Placeholder ...')
                ->searchBoxType(MapSearchBoxType::BUTTON)
                ->searchResultLimit(3)
                ->searchResultKeepOpen(true)
                ->withTransformation()
                ->transformScale()
                ->transformRotate()
                ->transformStretch()
                ->required()
                ->requiredOnCreate()
                ->requiredOnUpdate()
                ->stacked()
                ->capture(
                    Capture::make('location_screenshot', 600, 600)
                        ->disk('location')
                        ->maxZoom(9)
                        ->padding([10, 10, 10, 10])
                        ->nearest(true)
                        ->prunable(true)
                    
                )
                ->default(
                    PointValue::make(51.5887845, 4.7760237)
                ),
        ];
    }
}

Migration

From 3.* to 4.*

Support for matanyadaev/laravel-eloquent-spatial versions 2 and 3 has been dropped. The package now exclusively supports version 4 and higher.
The HasSpatialColumns trait has been removed from the package. Instead, use the HasSpatial trait from the laravel-eloquent-spatial package.
Both MapSearchBoxType and MapSearchProvider custom enums have been refactored and are now located in the Mostafaznv\NovaMapField\Enums namespace, utilizing PHP 8.1 enums. This update affects:
- The searchBoxType and searchProvider methods across all map field types (MapPointField, MapPolygonField, MapMultiPolygonField)
- The configuration file properties search.box-type and search.provider.

Therefore, if you decide to use my packages, please kindly consider making a donation. Any amount, no matter how small, goes a long way and is greatly appreciated. 🍺

License

This software is released under The MIT License (MIT).

mostafaznv / nova-map-field

Maintainers

Details

README

Requirements:

Laravel Compatibility

Installation

Install the package via composer:

Publish config and assets:

Done

Usage

Create table with spatial fields

Add `HasSpatial` trait to model

Define spatial columns of model

Add map fields to resource

Done

Map Field Methods

Config Properties

Capture Screenshot

Using Spatial Columns over Application

Tricks

Transform Polygons

Select Polygons

Complete Example

Migration

From 3.* to 4.*

License

Sponsors

mostafaznv / nova-map-field

Maintainers

Details

README

Requirements:

Laravel Compatibility

Installation

Install the package via composer:

Publish config and assets:

Done

Usage

Create table with spatial fields

Add HasSpatial trait to model

Define spatial columns of model

Add map fields to resource

Done

Map Field Methods

Config Properties

Capture Screenshot

Using Spatial Columns over Application

Tricks

Transform Polygons

Select Polygons

Complete Example

Migration

From 3.* to 4.*

License

Sponsors

Add `HasSpatial` trait to model