Phpgmaps Laravel Package

Product Decisions This Supports

• Keep / contain / replace triage on inherited Laravel applications. Finding genealabs/phpgmaps in a composer.json is an audit finding, not a platform decision. In practice it flags an address-lookup, store-locator, property-listing, or delivery-estimate feature built server-side around 2017 and never revisited. The decision it supports is effectively binary — contain now, replace at the next upgrade — and the evidence (archived, last release 0.4.3 on 2017-10-14, 27 stars, 0 dependents, MIT) all points the same direction.
• Build vs. buy vs. wrap. There is no "buy" option here. With a composite score of 0.6275, an opportunity score near the floor, and no maintenance path, the realistic options are (a) call Google's Geocoding / Directions / Distance Matrix web services directly from a small internal service class, or (b) keep existing call sites behind a thin internal interface until they can be retired. "Adopt this package for new work" is not a third option, and a PM should say so explicitly in the ticket so nobody re-litigates it.
• Roadmap sequencing and upgrade gating. Anything customer-facing that touches addresses or routing inherits a 2017-era API surface plus outdated Google key and billing assumptions. That makes "replace the maps wrapper" a prerequisite ticket inside the Laravel/PHP modernization epic, not a parallel workstream. It is the dependency most likely to break first during a version bump — and it will break mid-upgrade, when the team has the least slack. Sequencing it early is a schedule-risk decision, not a cleanup preference.
• Scoping what stays in bounds. Legitimate remaining scope is narrow: internal, low-traffic, read-only, server-side lookups — geocoding one address in a back-office form, an admin-only distance estimate, a throwaway internal tool with a declared end-of-life date. Explicitly out of scope for planning purposes: customer-facing map rendering, Places autocomplete, interactive directions, marker clustering, mobile/SPA surfaces, and anything carrying an uptime, accessibility, or privacy commitment. Deciding this boundary is what keeps the "contain" period honest rather than open-ended.
• Dependency governance precedent. A real instance beats arguing the principle abstractly. Single maintainer, archived with no CVE response path, no ecosystem validation (zero dependents), and a hard transitive dependency on Google's API key and billing model are three arguments in one repository. Use it to land the policy rule — no new adoptions of archived packages — and to justify adding an archive check to the dependency review checklist.
• Quota, cost, and data-egress budgeting. Because geocoding is deterministic per address string plus locale/region, the caching decision is a product decision: a persistent, provider-tagged geocodes table caps quota exposure, survives any package replacement untouched, and produces an audit trail of what address data has left your system. For teams with privacy or vendor-review obligations, that trail is often the artifact that unblocks the feature.
• Risk acceptance with a named owner. Containment is a decision someone owns. The PM should record the exit plan, the trigger condition (next Laravel/PHP major, or first CSP requirement on map markup), and the replacement scope (Geocoder / RouteEstimator / MapRenderer against Google's web services directly, plus the DB-backed cache) alongside the ticket.

When to Consider This Package

Consider it — narrowly, and only in these conditions:

• You are inheriting, not starting. The package is already installed and working in a back-office or internal tool, and the only decision on the table is whether to rip it out now or contain it. Ripping out working code mid-quarter is rarely the highest-value use of engineering time.
• The use case is server-side, low-traffic, read-only. A single geocode in an admin form, a nightly batch that backfills coordinates, an internal distance estimate. No customer-facing SLA, no accessibility commitment, no interactive map UI.
• You can wrap it on day one. If the team will commit to an internal contract (Geocoder, RouteEstimator, MapRenderer) with the package as a single swappable implementation, the blast radius of the archive is contained. If the team intends to call the facade from controllers and Blade templates, do not proceed.
• International addresses are in scope only on 0.4.3 or later. Earlier releases have a lookup-URL bug that breaks non-Latin alphabets. 0.4.3 is a hard floor, and it should be pinned exactly so a future composer update cannot float it into an untested state.
• You can accept the security and platform conditions. That means: escape/XSS mitigation at your own boundary for any user-influenced string reaching a marker title or info-window, a CSP strategy that tolerates or nonces inline script output, and a verified PHP/Laravel compatibility result from a throwaway branch — not an assumption.
• You have a kill switch and an exit date. A MAPS_DRIVER config flag and a declared end-of-life make containment a bounded decision instead of a permanent one.

Look elsewhere — meaning build the thin internal service against Google's web services directly, or drop maps entirely — when any of the following is true:

• Greenfield work. There is no argument for adopting an archived, zero-dependent, 2017 package for new code. The wrapper's total value is saved boilerplate, and a thin HTTP client is not meaningfully more work.
• Any customer-facing surface. Map rendering, Places autocomplete, interactive directions, clustering, location search on a marketing site — all require a package with a maintenance path, current key-restriction support, and a CSP story.
• You have a Content Security Policy today. Inline <script> emission fails under any policy without 'unsafe-inline', and the package has no nonce concept. This is frequently the trigger that forces the replacement conversation; surfacing it at deploy time is expensive.
• The feature is thin enough to eliminate. For internal-only tools, a static map image URL and a plain outbound Google Maps link often removes the dependency entirely for an afternoon of work. Elimination beats replacement beats containment.
• Your platform floor has moved past what the package supports. Do not widen your PHP or Laravel support matrix to accommodate a 2017 dependency. Isolate it behind a legacy service boundary or remove it.
• You are tempted to fork. MIT permits it, but a fork converts abandonment risk into ownership cost without removing upstream API-churn risk. Fork only for a single CVE-class fix, keep it private, and record the owner and exit plan with it.

How to Pitch It (Stakeholders)

To executives — one paragraph. A dependency audit surfaced genealabs/phpgmaps, a Google Maps wrapper last released in October 2017 and now archived. It has no maintainer, no security patch path, and no other projects depending on it. It currently supports internal, low-traffic address and distance lookups — a low-value but non-zero surface. My recommendation is to contain it rather than adopt it: pin the version, put it behind a small internal interface so it can be swapped in one place, add a caching table so we stop paying for the same lookups repeatedly, and schedule replacement as a prerequisite ticket in the platform upgrade already on the roadmap. Cost of containment is roughly a day of engineering; cost of leaving it unmanaged is an outage or a security gap discovered during that upgrade, when the team has no slack. No new work will be built on it.

To engineering — the summary and the ask.

• Status: archived (0.4.3, 2017-10-14), 27 stars, 0 dependents, MIT. Treat the source as frozen vendor code we have audited, not a dependency we can lean on. Do not subclass it, do not patch vendor/.
• The ask: (1) pin genealabs/phpgmaps:0.4.3 exactly; (2) no new \Phpgmaps:: call sites — add a review checklist entry that blocks them; (3) route any existing call through an internal contract, bound in a service provider, so replacement is a one-class, one-binding change; (4) add timeout and error handling at the adapter — the wrapper is a request builder with no retry, backoff, or timeout logic, and geocoding must never run in the request cycle for batch work.
• Correctness traps to code for: check the payload status, not truthiness — Google returns HTTP 200 with ZERO_RESULTS, OVER_QUERY_LIMIT, REQUEST_DENIED, or INVALID_REQUEST, so a wrapper that "works" on happy paths silently returns empty data when a key is misconfigured or quota is blown. Log the constructed URL (minus key), HTTP status, and raw decoded payload before transformation. Use separate keys for server-side (IP-restricted) and browser (referrer-restricted) calls, and confirm billing is enabled — a disabled billing account produces errors that look identical to a bad key.
• Test posture: bind a stub implementation for the whole suite. Any test that reaches Google is flaky, slow, costs money, and will block CI once the key is restricted.
• What we are not doing: no customer-facing map rendering, no Places autocomplete, no interactive directions on this dependency. If a roadmap item needs those, it needs a replacement — the wrapper predates Google's current key-restriction and billing model, and it emits inline JavaScript that a CSP will reject.
• Exit plan: size the replacement — Geocoder/RouteEstimator/MapRenderer against Google's web services directly, plus the DB-backed geocode cache — as a prerequisite in the modernization epic. The cache table survives the swap untouched, so the work done now is not thrown away. Have the exit conversation before the next framework upgrade, not during it.