Nova Google Polygon Laravel Package

Technical Evaluation

What this package is (from the release evidence): a Laravel/Nova field package (jamesil/nova-google-polygon) that captures Google Maps polygon geometry in a Nova resource and exposes a server-side Polygon::contain() point-in-polygon predicate. The TPM-relevant surface is therefore not the map UI but the containment predicate — it is the component that encodes business rules (service eligibility, territory/zone assignment, delivery coverage, risk geofencing) into code.

Architecture fit: Good for Laravel/Nova-centric apps that need lightweight geofencing without standing up PostGIS. contain() is a pure PHP computation over stored geometry, so it fits cleanly into form validation, Nova actions, queued jobs, and policy checks. It is not a spatial index or query engine — any workload of the form "which of N polygons contains this point" scales linearly and needs an application-level bounding-box prefilter or a real spatial store. Treat it as a rule evaluator, not a geospatial database.

V2.1.1 significance: This is a correctness release, and the defect class it closes is the one that matters most for a TPM — silent wrong answers. The prior implementation returned incorrect results whenever the queried point shared a longitude with a vertex, and threw ValueError for coordinates near the equator (scientific-notation strings reaching bccomp). Wrong-but-successful geofence decisions produce incorrect business outcomes with clean logs and green dashboards; that is materially worse than an outage.

Technical risk assessment:

Verification confidence — a positive signal worth recording: An exact-integer oracle across 8M+ comparisons over 155k convex, concave, and self-intersecting polygons with zero mismatches, plus an independent float reference across equator/meridian/extreme-magnitude regimes, is a materially higher bar than typical package test suites. From a TPM standpoint this converts the upgrade from "trust the changelog" to "trust but verify with your own fixtures."

Key questions for the maintainer / team:

1. Version-line mapping: the notes say Laravel 9–11 users should take 1.2.1 on the 1.x line, implying 2.x targets a newer Laravel/Nova baseline. What exactly is the supported matrix for 2.x (Laravel 12? Nova 5? PHP 8.2+)?
2. Is 1.2.1 functionally identical to 2.1.1 for this fix, or does the 1.x backport omit anything?
3. Does the client-side (Google Maps drawing widget) use the same half-open edge convention as contain(), or can UI and server disagree on boundary points?
4. Is ext-bcmath used anywhere else in the package, or was it solely a contain() dependency?
5. How does contain() behave for antimeridian-crossing polygons and polar coordinates — in scope, or explicitly out of scope?

Integration Approach

Stack fit: Laravel + Nova + composer. Upgrade is a single composer update jamesil/nova-google-polygon. No API change means no code edits, no config migration, no front-end rebuild. This is the cheapest possible upgrade shape.

Compatibility / migration path:

• Confirm your Laravel/Nova version before bumping. If you are on Laravel 9–11 you are on the 1.x line and the target is 1.2.1, not 2.1.1. Pinning ^1.0 vs ^2.0 is now a real constraint decision, not a formality — capture it in composer.json deliberately rather than letting the resolver decide.
• ext-bcmath removal is a deployment simplification: it unblocks minimal containers, shared hosting, and managed PHP runtimes where bcmath is absent. Verify nothing else in your app declares bcmath implicitly through this package's transitive needs.

Sequencing (recommended):

1. Pin the correct line for your Laravel/Nova version; upgrade in a staging branch.
2. Regression fixtures first: assemble a small canonical set of polygons and points — a vertex point, a point sharing a longitude with a vertex, an equator-adjacent point, an empty polygon, a 2-vertex degenerate polygon, a concave polygon, a self-intersecting polygon. Assert expected outcomes against the new half-open convention. These fixtures are your acceptance criteria and your permanent guardrail.
3. Re-evaluate stored/tallied outputs: identify records whose zone membership was computed under ≤2.1.0 and compare old vs. new classification. Any record that flips is business data that was previously wrong.
4. Confirm whether the flip set is tolerable (a handful of edge cases) or requires a backfill/audit and possibly customer communication.
5. Then run the degenerate-polygon path: find polygons with <3 vertices in production data and decide whether false is the desired answer or whether that should be a data-quality alert.

Ordering caution: do not bundle this with unrelated Nova or Laravel major upgrades. Because the behavior change is silent (wrong → right; error → false), you want a clean diff where any observed change in business outcomes is attributable to exactly this package.

Operational Impact

Maintenance: Low ongoing cost — small package, narrow responsibility, no configuration surface described. The upgrade carries no migration burden. The one durable maintenance obligation is documenting the boundary convention in your own domain docs, because the next engineer who touches a geofence rule will otherwise assume "on the line" is undefined behaviour. Half-open semantics (min-latitude and min-longitude edges inclusive) are correct and standard, but they are only safe if written down.

Support surface: No API change means no developer retraining and no client-facing API contract change. Support risk concentrates in a single question: "why did this location's zone assignment change?" Pre-brief support/success teams that boundary and near-equator results may shift, and that the shift is a correction, not a regression.

Scaling: Ray casting is O(n) in vertices per query and re-evaluates geometry on every call. Practical limits:

• Fine for single-point checks on typical admin-drawn polygons (tens to low hundreds of vertices).
• Not fine for batch operations (nightly re-geofencing of every record, per-request loops over many polygons). Plan memoization of parsed geometry, a bounding-box prefilter, and a chunked job — or move the predicate into PostGIS/ST_Contains if geofencing becomes a primary workload.
• Removing bcmath also removes a per-comparison string-math cost, which should be a modest throughput improvement on hot paths — worth measuring rather than assuming.

Failure modes to monitor:

1. Boundary ambiguity — points exactly on vertices or min-latitude/min-longitude edges. Deterministic now, but must match the business definition of the zone. This is a product decision, not just a code one.
2. Degenerate polygons returning false — an admin saving a malformed polygon (fewer than three vertices) now yields "not contained" silently. Instrument this: log/alert on degenerate geometry at write time rather than discovering it as a coverage gap.
3. Self-intersecting polygons — verified by the oracle as handled, but the business meaning of containment in a self-intersecting ("bowtie") polygon may not match what the map author intended. Validate geometry on save.
4. Geographic edge regimes — antimeridian and polar cases are unverified by the release notes; confirm scope explicitly before using this package for coverage rules in those regions.
5. Unflagged historical drift — previously wrong classifications still resident in downstream reports, billing, or eligibility records.

Ramp-up: Very low for developers — no new API, no new concepts. The genuine ramp-up cost is organizational: establishing that geofence correctness is a business-critical invariant with fixtures and monitoring attached, not a UI nicety. Budget roughly a sprint-day for the regression fixture set, the flip-set comparison, and the convention documentation; treat the backfill decision separately if the flip set is non-trivial.

TPM recommendation: Upgrade, and prioritize doing so — the pre-2.1.1 behavior is a live silent-correctness defect in any application that geofences near the equator or along shared longitudes. Sequence it as a correctness change with an explicit audit step, not as a routine dependency bump. Confirm the 2.x vs 1.2.1 line mapping as the sole blocking gate before scheduling.