Map Multi Polygon Laravel Package

Getting Started

• Install via Composer: composer require wm/map-multi-polygon (confirm vendor/package name from the repository README). Pin at least ^1.0.4 — earlier patches lacked null handling in fillModelWithData().
• Publish any package assets/config if supported: php artisan vendor:publish --tag=map-multi-polygon or check README.md for the exact tag.
• Register the field in a Nova resource:

  use Wm\MapMultiPolygon\MapMultiPolygon;
  
  public function fields(Request $request)
  {
      return [
          MapMultiPolygon::make('Area'),
      ];
  }
  

• Look first at the repository’s README.md, src/, resources/js/components/, and config/ if present. The Vue component shows the expected value shape; the PHP field class shows meta() defaults, fillModelWithData() hydration behavior, and serialization.
• First use case: add a json or spatial column to a model, expose it through Nova with this field, draw one or more polygons, save, then inspect the stored payload in Tinker. Confirm it is GeoJSON MultiPolygon or an array of polygon coordinate rings before building further logic. Also test saving the field empty/null on both create and update to confirm your installed version behaves as expected.

Implementation Patterns

• Store the value in a JSON/geometry column. Use a model cast such as 'area' => 'array' or a custom cast that normalizes the field output to GeoJSON MultiPolygon.
• Keep the Nova field as the editor, and put spatial logic in model observers/accessors: calculate area, centroid, bounding box, or convert to a spatial column with PostGIS/MySQL after save.
• Validate before persisting. Add rules for valid GeoJSON, closed rings, coordinate bounds, and non-empty geometry. Prefer a custom rule so the same validation runs outside Nova.
• For PostGIS:

  DB::statement('ALTER TABLE areas ADD COLUMN geom geometry(MultiPolygon, 4326)');
  

  Then in a saved observer: ST_GeomFromGeoJSON(?). For MySQL, use ST_GeomFromGeoJSON with SRID 4326 consistently.
• Prefill editing forms from an accessor that returns exactly the shape the field expects. If legacy data is stored as WKT, convert to GeoJSON first.
• Use Nova dependency methods (dependsOn, hideWhen, readonly) for workflows where geometry is only editable after a type/category is chosen.
• For read-only detail/index views, use the same field with ->onlyOnDetail() or ->exceptOnForms() if supported, or fall back to a custom Nova component.
• Integrate map provider settings through the field’s meta() or package config: tile URL, default center, zoom, drawing controls, and API key (if any).
• Test serialization outside the browser: unit-test model casts, null/empty handling, GeoJSON validation, and spatial conversion. Use Nova Dusk only for the map interaction itself.

Gotchas and Tips

• GeoJSON coordinate order is [longitude, latitude], not [latitude, longitude]. Most map errors come from swapped coordinates.
• Polygon rings must be closed: first coordinate equals last coordinate. MultiPolygon is an array of polygons, each polygon an array of rings.
• Ring winding order can matter for some renderers and spatial engines: RFC 7946 expects counterclockwise exterior rings and clockwise holes.
• Null/empty state: fillModelWithData() null handling was only fixed in v1.0.4 (2025-05-27), so earlier versions can error when hydrating a record whose geometry is null. If you are on 1.0.3 or below, upgrade before relying on nullable columns, and still normalize deliberately — saving null, [], or an empty MultiPolygon may produce different database values or break spatial casts. Cover create, update, and clear-the-geometry flows in tests.
• MySQL/PostGIS SRID mismatches cause silent failures or invalid geometry errors. Keep SRID 4326 end-to-end unless you have a reason not to.
• Large hand-drawn geometries bloat JSON payloads and slow Nova forms. Limit vertices or simplify server-side before saving.
• Tile provider API keys may be exposed in the browser through field metadata. Use restricted/public keys and configure allowed origins.
• The package has minimal stars/dependents and small patch releases. Pin the exact version (e.g. 1.0.4), read the changelog before upgrading, review the source, and wrap storage-format assumptions in tests. Expect limited community support.
• If the field fails to render, check published assets, npm/Vite build output, Nova version compatibility, and browser console errors. Inspect the Nova field response in the network tab for the meta payload.
• Extension points are usually the Vue component, field meta(), config file, and model cast. Prefer a custom cast/validation rule over editing vendor code so upgrades remain possible.
• Debug by logging the exact value received in fill()/resolve()/fillModelWithData() and comparing it to what the map component expects. Most “map doesn’t load” bugs are shape or null mismatches, not map rendering bugs.