Kml Parser Laravel Package

Technical Evaluation

Architecture fit. The package is a thin, framework-native wrapper rather than infrastructure: one service (KmlParser), one extractor (KmzExtractor), one facade, a publishable config, and an exception hierarchy (KmlException → KmlParserException / KmzExtractorException). It slots into the Laravel service container with no adapters, no drivers, and no queue or cache coupling. For a TPM this is the favourable shape — the integration surface is roughly ten methods, so the cost of adoption is dominated by our own ingestion pipeline around it, not by the package itself. It is a leaf dependency: it parses, it does not persist, schedule, or emit events. That means it can be introduced behind a single service class and swapped later without touching controllers or jobs.

Integration feasibility. High, with a short path to a working spike. composer require plin-code/kml-parser, publish config, call loadFromFile()/loadFromKmz()/loadFromString(), read getPlacemarks(), getStyles(), getStyleMaps(), getDocumentName(), getDocumentDescription(), or toGeoJson(). The 3.1.0 work is genuinely reassuring on engineering hygiene: PHPStan raised from level 5 to level 9 with an empty baseline and no @phpstan-ignore suppressions, test count moved from 79 to 91, and three real defects were fixed — including a KMZ archive-limit setting that a non-numeric config value silently reinterpreted as "limit disabled." That last one is the kind of bug that only gets found by someone actually thinking about failure direction. The stated constraint that GeoJSON conversion now degrades to null/0.0 on malformed geometry rather than throwing a TypeError is a deliberate reliability trade-off we should accept knowingly.

Technical risk. The risk is almost entirely supply-chain and longevity, not code quality:

The concrete technical risks: memory and DoS exposure — the parser loads the entire document into a DOM and runs a single //kml:Placemark XPath, so a 20 MB KMZ from an untrusted upload is a request timeout at best. KMZ extraction writes to disk (KmzExtractor::extractAllFiles(), configurable temp directory), which is a path-traversal and disk-exhaustion surface that must be treated as untrusted-input handling. README is stale relative to the shipped config, so php artisan vendor:publish output — not the docs — is the source of truth.

Key questions for the maintainer or our own spike: which PHP and Laravel versions are actually supported (composer constraints, not README prose)? Is temp_directory cleaned up on failure? Does KMZ extraction sanitise entry names against ../ traversal? Is there any internal ceiling on KML (not just KMZ) document size? What is the maintainer's stated support posture — best-effort hobby project, or intended for production? And why does the release metadata show a future-dated 3.1.0 — a tagging artefact or a mirrored repository?

Integration Approach

Stack fit. Native Laravel: service provider, facade, publishable config, Composer install. No PHP extensions beyond the standard XML/DOM and Zip families that a normal Laravel image already carries. It fits the same slot as any other "parse a file, get an array" utility and composes cleanly with Storage, queues, and validation.

Migration path. There is nothing to migrate from unless we already hand-roll SimpleXML. If we do, the sequencing is replace-in-place behind a boundary. If we are greenfield, the package goes in as the first implementation of a MapFileImporter interface we own:

interface MapFileImporter {
    public function import(string $absolutePath): ParsedDocument;
}

Return a DTO, not the raw array. The maintainer explicitly keeps placemarks as a heterogeneous map — the 3.1.0 notes say so — meaning the folder key that appeared in 3.1.0 is additive but will break whole-array === comparisons. Normalising once at the boundary is the only place in the codebase where we think about missing keys. This single decision is what converts the package from a lock-in into a swappable dependency: if the project stalls, we reimplement MapFileImporter against SimpleXML and nothing downstream changes.

Compatibility. Two compatibility axes to pin in the spike: Laravel/PHP version constraints from composer.json, and KML dialect coverage. The config exposes a single namespace default (http://www.opengis.net/kml/2.2); vendor exports from Google My Maps, ArcGIS, or niche GPS tooling frequently ship non-standard or unnamespaced KML. Our acceptance criteria should be a corpus of real files from the actual sources we expect, not a synthetic fixture.

Sequencing. (1) Spike — install, parse three representative real-world files (flat KML, foldered My Maps export, KMZ with embedded images), record output shape. (2) Wrap — MapFileImporter interface + ParsedDocument DTO + KmlImportService handling the .kml/.kmz branch, size guard, and KmlParserException catch in one place. (3) Harden — enforce an upload byte ceiling at the validation layer before the parser sees the file, and confine temp_directory to a per-job scratch path that is removed in a finally. (4) Offload — move parsing into a queued job with an explicit $timeout, since there is no streaming path. (5) Release behind a feature flag so the parse pipeline can be rolled back independently of upload.

Operational Impact

Maintenance. Low day-to-day, non-trivial in aggregate. Dependency updates are cheap — MIT licence, no transitive weight worth speaking of. The maintenance cost is ours, not theirs: with a single maintainer and no dependents, we effectively own the risk of every future PHP/Laravel major. Budget for the possibility of vendoring the package and maintaining a fork; the codebase is small enough (level-9 PHPStan clean, 91 tests) that this is a realistic fallback rather than a rewrite. The PHPStan level 9 pass and the retained test suite are what make that fork option credible — that is the single most valuable signal in the whole repository.

Support. No commercial support, no SLA, no security policy beyond a template pointing at a security/policy file. Realistically: issues are best-effort from one person. We must not architect anything with a hard dependency on a fix landing. Version pinning and a documented internal owner for the fork are the mitigation. Treat "no releases for N months" as an expected state rather than an incident.

Scaling. Vertical and queue-bound, not horizontal. The DOM load plus single XPath means peak memory scales with document size and worker concurrency; a handful of large KMZ uploads in parallel can OOM a worker pool. Concretely: cap upload size at the edge, cap queue worker memory_limit, and set job $timeout generously (KML with thousands of placemarks is CPU-bound on XPath and coordinate splitting, not I/O). Disk is the second axis — extractAllFiles() writes every KMZ member to the temp directory, so a queue of KMZ imports needs scheduled cleanup of that scratch path or the volume fills silently. Throughput will be comfortably fine for background batch ingestion and unsuitable for synchronous per-request parsing of anything large.

Failure modes. Enumerate and handle these explicitly:

• KmlParserException on malformed XML, missing required elements (the KmlValidator pre-check), and — as of 3.1.0 — unreadable files, which now report Unable to read KML file: <path> rather than the misleading "String could not be parsed as XML." Distinguish unreadable from invalid in user-facing errors; they mean different things to the uploader.
• KmzExtractorException on corrupt, encrypted, or oversized archives, and on limits tripped. Note 3.1.0's fix: a non-numeric limit previously fell back to 0, which is the documented way to disable the limit. Post-3.1 it falls back to the documented default — but verify this in the published config, and treat any limit key as load-bearing config that needs a test.
• Silent shape drift on minor upgrades. folder was added to every placemark in 3.1.0 with "nothing removed and no message changed" — the 3.0→3.1 upgrade is genuinely composer update, but a strict-array test would have failed. Our DTO boundary absorbs this; raw array consumption would not.
• Partial geometry. Malformed coordinate or geometry data now yields null/0.0 rather than throwing. Downstream consumers must tolerate null coordinates — validate before persisting, or accept degenerate geometries.

Ramp-up. Very fast. A competent Laravel developer is productive in under a day: ten methods, a config file, and a clear exception boundary. The real onboarding cost is not the API but the KML format itself — folder nesting semantics, MultiGeometry, StyleMap indirection — and that knowledge lives in one person's release notes rather than formal documentation. Recommend capturing our own internal notes from the spike, because the README will not be updated in step with the code, and the changelog is the only accurate record of behaviour changes.