Geo Parser Laravel Package

Technical Evaluation

creof/geo-parser is a narrow, single-responsibility string parser that converts human-entered coordinate notations (decimal degrees, degrees-decimal-minutes, degrees-minutes-seconds, and hemisphere/bearing variants) into coordinate value objects. It is designed to compose with sibling creof packages (geo-io for geometry primitives, doctrine2-spatial for ORM persistence), which gives it a clean boundary: it should sit in a translation layer, never in domain logic.

• Architecture fit: Good for input normalization. It is stateless, deterministic, and side-effect free, so it slots cleanly behind a Laravel service provider or facade. It does not validate geography, resolve addresses, or reconcile datums — do not use it as a geocoder.
• Integration feasibility: Composer-installable, MIT-licensed, zero-infrastructure. A TPM can approve a contained spike in a single sprint. The real cost is a thin wrapper plus a Laravel validation rule, not the package itself.
• Technical risk: Material. Last release 2019-08-06 and 61 stars imply an effectively unmaintained package. Expect no PHP 8.1+ typed-signature guarantees, no security patching, and stale transitive constraints. Treat it as vendored source, not a trusted upstream dependency.
• Key questions: Which coordinate formats must we accept (decimal only vs. DMS/DM/UTM)? What PHP/Laravel version is the target? Do we only parse, or also persist via Doctrine/spatial columns? Is there a maintained alternative (brick/geo, geocoder-php, or a bounded regex in-house) that covers our subset? Who owns the fork if upstream is dead?

Integration Approach

• Stack fit: Compatible in spirit with any Laravel version, but verify composer.json PHP constraints against the app's runtime before committing. If the project is on PHP 8.2+ / Laravel 10+, assume a fork or patch is required.
• Migration path: Do not replace existing parsing logic wholesale. Introduce a CoordinateParser contract + adapter wrapping creof/geo-parser, bind it in a service provider, and route new code paths through it. Migrate legacy regex/explode logic format-by-format behind the contract.
• Compatibility: Build a fixture suite of real user inputs (mixed separators, hemisphere suffixes, negative decimals, whitespace, locale decimal commas). Add a Coordinate validation rule and FormRequest macro. Test on the lowest and highest supported PHP versions in CI.
• Sequencing: (1) Compatibility spike on target PHP; (2) wrapper package with contract + fixtures; (3) Laravel service provider, facade, and validation rule; (4) feature-flagged adoption in one endpoint; (5) expand formats and retire legacy parsers; (6) document supported grammar and failure semantics.

Operational Impact

• Maintenance: High relative to value. Budget for internal ownership: pin the version, fork to a private VCS or Satis mirror, and schedule dependency audits. Assume no upstream CVE responses.
• Support: No vendor support channel. Support burden shifts to the adopting team; document the supported notation set and the null/exception contract explicitly so downstream services handle failures uniformly.
• Scaling: Negligible runtime cost — pure PHP, in-process, stateless, no I/O. It will not be a bottleneck; horizontal scaling concerns are zero. Caching parsed coordinates where repeated is a cheap win but not required.
• Failure modes: Unparseable input returning null/exception must be handled as a validation error, not a silent default. Ambiguous hemisphere/bearing parsing and locale decimal separators are the highest-risk correctness bugs. Also watch for dependency drift breaking autoloading on PHP upgrades.
• Ramp-up: Low for engineers (small API surface), but domain literacy in coordinate notations is required to review fixtures. Plan half a day of onboarding plus the fixture corpus; the institutional knowledge lives in tests, not docs.