Kml Parser Laravel Package

Product Decisions This Supports

• Build vs. buy for a geo-import feature. KML/KMZ ingestion ("let users upload a Google Earth / Google My Maps file") looks like a 2–3 day task and is not: zip extraction, XML namespaces, folder hierarchy, style maps, and a usable error taxonomy are the long tail. This package (MIT, no license cost, small API) absorbs that tail and lets us defer the build decision.
• Roadmap sequencing. If geo import is a supporting capability rather than the product itself, this turns a multi-sprint item into a ticket. That frees the roadmap slot for the features that actually differentiate us.
• Feature scope and use cases it unlocks: bulk store/dealer locator uploads, field-survey and inspection ingestion, property/parcel boundary import, route and waypoint import for logistics, and environmental/site mapping.
• Preserving user intent from layer names. v3.1.0 keeps <Folder> paths on each placemark (['Piemonte', 'Laghi']). In a Google My Maps export those layer names are usually business meaning — category, region, owner. Flattening them (what the package did before) would have silently destroyed data users curated.
• Rendering strategy. toGeoJson() means an imported file can be previewed on the existing Leaflet/Mapbox stack before commit — a "confirm what you're importing" step we can ship cheaply rather than building a KML renderer.
• Packaging/pricing experiments. Because the cost to ship is low, "geo import" is a viable gate for an upper tier; we can test willingness to pay before investing further.
• Lock-in posture. The public surface is roughly eight methods and the license is permissive. Wrapping it behind our own service and DTO means the swap cost if we outgrow it is contained to one class — adopting does not foreclose alternatives.

When to Consider This Package

Adopt when:

• We're on modern Laravel/PHP and need read-only server-side parsing of .kml/.kmz.
• Files are modest (single-digit MB), user-supplied or batch, and the parse can run off the request thread in a queue.
• We mainly need placemarks, coordinates, folder paths, and document metadata; styles/style maps are a bonus.
• We want a dependency with semver releases and a real changelog rather than hand-rolling XPath and zip handling.
• We accept owning the wrapper: typed DTO normalization, upload byte ceilings, and error-to-user-message mapping.

Look elsewhere when:

• Large or adversarial files. The parser loads the whole document into a DOM with a single XPath and has no streaming path or internal size ceiling. A 20 MB KMZ is a timeout and a trivial DoS. Look at SAX-based parsing, a CLI worker, or GDAL.
• We need to write KML, or full spec coverage (NetworkLink, GroundOverlay, TimeStamp, ExtendedData/custom schemas, gx: extensions). The maintainer's own v1.0.0 note says support is still evolving.
• We need multi-format geo (Shapefile, GPX, GeoJSON ingest, reprojection) — that's a broader geo/GDAL/PostGIS decision, not a parser choice.
• Procurement needs vendor support, an SLA, or a security review at enterprise scale. Three stars, zero dependents, one maintainer: bus factor 1.
• Stable typed return shapes are a hard requirement. Placemarks are deliberately heterogeneous arrays; the type system won't protect consumers. We must normalize at the boundary.
• Geo import becomes core to the product rather than incidental — at that point owning it is the cheaper long-term bet.

How to Pitch It (Stakeholders)

For executives: This is a free, MIT-licensed building block that lets us ship "import a map file" in days instead of weeks. No license cost, no vendor contract, and no lock-in — the whole API is a handful of methods that we wrap in our own interface, so replacing it later touches one class, not the product. The risk is not the code quality (it has tests, static analysis at its strictest level, and a maintained changelog); the risk is that it's a single-maintainer project with almost no adoption. We mitigate that with our own wrapper, our own test coverage around the import flow, and a queue plus file-size limit so a bad upload can't take the app down. Recommendation: adopt behind a wrapper for non-core imports; revisit if geo becomes core or file sizes grow.

For engineering: Laravel package, MIT, plain PHP DOM/XPath, service provider + facade + publishable config. Handles KML and KMZ (zip), configurable namespace and temp directory, folder hierarchy on placemarks, GeoJSON export, and a validator plus exception hierarchy so bad input fails predictably rather than as a generic XML error. 91 tests, PHPStan level 9 with an empty baseline — unusual discipline for a package this small. Known trade-offs to design around: whole document in memory, no streaming, no internal size cap; arrays rather than DTOs; and the README drifts from reality (the config snippet is stale and the KMZ archive limits aren't documented) — publish the config and read the v3.1.0 release notes as the source of truth. Integration plan: one KmlImportService that branches on .kml vs .kmz, normalizes to our own DTO, and is invoked from a queued job with an upload byte ceiling enforced before the parser ever sees the file.