Nova Map Field Laravel Package

Technical Evaluation

Architecture fit. This is a presentation-layer component, not a platform. It registers a Nova field, renders a map picker in Vue, and writes two scalar attributes (latitude, longitude) onto the host model. There are no models, migrations, service providers worth reasoning about, queues, or API surface introduced into the domain. That is the right shape for a TPM decision: the coupling is to the admin UI only, and the data contract (plain decimal(10,7) columns) is owned by us, not the package. Adoption therefore does not constrain future geospatial work — it captures origin data that "near me" search, distance sorting, or coverage views would later consume, without delivering any of those capabilities itself.

Integration feasibility. Low effort: one composer require, one field registration per resource, asset publish/build, provider configuration. The realistic effort is not the install — it is the surrounding work a TPM must budget for: schema columns, server-side validation rules, CSP allowlisting for tile and geocoding domains, a thin local subclass wrapper, and an operator pilot. Estimate a pilot as days, not weeks, but do not treat "it renders on my machine" as done.

Technical risk. The package profile is the dominant risk, not the code: 46 stars, zero dependents, MIT, and a maintainer roster that only recently widened past a single author. Release 4.4.0 (Laravel 13 support) is a genuine positive maintenance signal, but it is one data point and appears to be a dependency-constraint widening rather than proof of a tested matrix. Nova's field API evolves independently of Laravel, and the changelog says nothing about Nova majors — so framework compatibility must not be read as field compatibility. Secondary risks are conventional: front-end asset publishing and CSP are the most common cause of a blank map in production; client-side geocoding may expose an API key and quota; tile, style, and marker licensing are separate from the MIT licence; and there is no vendor support path or SLA. This is acceptable for a supporting admin capability and unacceptable on the critical path of a revenue feature.

Key questions to resolve before committing.

• Which exact (Nova major, Laravel, PHP) triple is validated — asserted in the README, or actually exercised in CI? Can we reproduce it on staging?
• Does address search/geocoding run client-side (key visible in the browser, quota abusable) or server-side? What provider keys and referrer restrictions are required?
• Which map providers/tiles are supported, and does that match our API-key policy, licensing posture, and any offline or air-gapped requirement?
• Does the field round-trip a resolved value cleanly through our attribute naming, form requests, and any existing mutators?
• Does any operator need keyboard-only input? If so, the numeric fields are mandatory, decided at pilot time.
• What is our containment plan if upstream stalls — who owns the fork-or-replace decision, and by when?

Integration Approach

Stack fit. Assumes an existing Laravel Nova admin panel on a supported version. The field is additive and per-resource, so it fits incrementally with no architectural negotiation. If Nova vs. Filament vs. bespoke admin is still an open decision, this is a minor vote for Nova in the TCO comparison for geo-heavy back offices — not a deciding factor.

Migration path. Add nullable decimal(10,7) latitude/longitude columns (plus optional address and zoom) — never a JSON blob, so swapping to a custom field or plain inputs later is a UI change rather than a data migration. Register the field on one low-risk resource where an operator currently types coordinates (Store, Venue, Warehouse, JobSite), keep the existing numeric inputs alongside it, and backfill existing records with an idempotent, rate-limited queued geocoding job — not inside the migration.

Compatibility. Pin ^4.4, commit the lockfile, and verify the (Nova, Laravel, PHP) triple on staging before writing resource code. Re-run the smoke test after any composer update, since transitive resolution can shift. Wrap the vendor field in a thin local subclass so a fork, swap, or hand-rolled Vue component is a one-file change across every resource — this is the exit path the package's risk profile assumes and the highest-value pattern available here.

Sequencing.

1. Confirm the compatibility triple and prove it on a staging build.
2. Install pinned; publish config/assets; run the Nova asset build; register the provider and key.
3. Add coordinate columns; decide nullability and the both-present-or-both-null rule.
4. Ship the thin subclass and register it on one resource behind a feature flag, with numeric fields still visible.
5. Add server-side validation (between:-90,90 / between:-180,180, required_with) and CSP allowlisting.
6. Run the operator pilot for a sprint; capture accuracy and preference evidence.
7. Fan out to additional resources only on positive pilot signal.
8. Treat server-side geocoding, radius search, and customer-facing maps as separate roadmap bets with separate scoping.

Operational Impact

Maintenance. Small footprint, but not zero-touch: pinned version, lockfile discipline, and a named owner who reviews Nova major upgrades and watches upstream activity. The subclass wrapper converts an upstream stall from a project into an afternoon. Schedule a periodic check that the field still round-trips values after Nova upgrades, since Nova's field API moves independently of Laravel.

Support. No vendor support path exists. Support load lands on the internal team and is dominated by a small number of recurring symptoms — blank or unstyled map — which should be documented as a runbook in a fixed order: assets published and provider registered, asset build run, browser console 404s, CSP blocks, provider key. Operator-facing support is minimal because the interaction is a click-and-drag.

Scaling. Server-side load is negligible; the field stores two decimals. The real scaling surface is third-party: tile requests and geocoding quota. Keep any bulk or reverse geocoding server-side, queued, rate-limited, idempotent, and cached — never triggered synchronously by an operator save. Confirm whether in-field address search is client-side and restrict the key by referrer or origin accordingly.

Failure modes to plan for.

• Blank map in production: asset build or CSP misconfiguration — the classic regression that works in local dev.
• Silent no-save: latitude()/longitude() pointing at the wrong column names, or a form request / mutator overwriting the value.
• Invalid data accepted: the UI makes coordinates look always-present but enforces nothing; bounds and pairing must live server-side.
• Key exposure and quota abuse if geocoding is client-side.
• Provider outage or key expiry degrading the admin form — mitigated by always-present numeric inputs.
• Accessibility gap for keyboard-only operators if the numeric fallback is removed.
• Data leakage: map requests can expose operator-entered addresses to third parties; flag to security/legal before production under GDPR-style regimes.

Ramp-up. Hours for engineering, one sprint for the pilot. Operator training is a short demo plus the numeric fallback; the measurable outcome is fewer coordinate-entry errors and less downstream cleanup. Keep the capability behind a config flag so operators can be switched back without a deploy, and confine usage to a handful of resources so the dependency stays a convenience layer over our own coordinate columns rather than a load-bearing component.