Json Parser Laravel Package

Technical Evaluation

Architecture fit. This is a framework-agnostic, single-purpose library with no service provider, facade, config, or contract — it will never feel Laravel-native. Its actual shape (per code-level review) is JSON → one-or-more CSV files written to a temp directory and returned as CsvFile/File value objects, driven by a Parser orchestrator with Structure and Analyzer/Strategy internals. That fits a service/worker layer — queued jobs, artisan commands, scheduled exports — and is a poor fit for anything on the request/response path, since output is file-oriented and must be read back, moved, or streamed manually. Plan to own a thin adapter (JsonToCsvExporter interface + implementation) and treat the package as an implementation detail. The build-vs-buy case only holds if we want its flattening semantics (dot-notation nested-object keys, generated parent-link columns per nested array) rather than our own.

Integration feasibility. Mechanically easy: composer require, PSR-4, MIT. The friction is transitive and environmental — it pulls Keboola's php-temp/php-utils, which assume a writable system temp directory and Symfony Filesystem semantics. In a containerized Laravel app that means either pointing it at storage/app/... explicitly or accepting sys_get_temp_dir() on a sized, monitored tmpfs. It also expects a PSR-3 logger in the constructor, so binding it as a singleton in AppServiceProvider is the sane wiring. Realistic wrapper effort: roughly one engineer-day for binding, config, and translating file objects into Storage puts, plus test work.

Technical risk. Stewardship dominates, not code quality. Six stars, zero dependents, composite 0.41, opportunity 15.87 — we are effectively the only external QA on this library. It is Keboola-funded and MIT, so forkability caps the downside, but expect slow issue triage and no commercial support absent a Keboola relationship. A material documentation risk sits on top: the package listing describes a generic JSON parser returning native PHP arrays with clear exceptions, while the code and sibling reviews describe a JSON→CSV flattener producing file objects. That mismatch means we cannot trust the summary metadata and must validate behavior against real payloads before committing. Secondary risks: opinionated, largely non-configurable flattening around heterogeneous arrays (column explosion, silently inconsistent headers), lossy type inference on leading-zero strings and large integers, memory-bound decoding of monolithic documents, and CSV formula injection if humans open the output in Excel. Pin the exact version; treat upgrades as manual review.

Key questions. What are the real payload shapes and maximum document size? Do downstream consumers depend on exact header naming and ordering (i.e., is the dot-notation + child-table contract acceptable)? Which is the true API — array-returning parser or CSV-file flattener — and does the release we'd pin match the description? Is there a hard streaming requirement above ~100 MB? Do we need per-field type overrides the library won't provide? Who owns the fork if upstream goes quiet?

Integration Approach

Stack fit. Pure PHP, Composer, PSR-4 — compatible with Laravel 10/11 on PHP 8.1+ provided the pinned release's PHP constraint allows it (verify first; older Keboola releases lag). Nothing conflicts with Octane beyond the temp-file assumption. Use it exclusively inside ShouldQueue jobs and console commands; never call the parser class from controllers or models.

Migration path. Adopt behind an interface, full stop. Define App\Contracts\JsonToCsvExporter with something like export(string|array $json, ExportOptions $options): ExportedFile; implement KeboolaJsonToCsvExporter wrapping Parser, and bind it as a singleton in AppServiceProvider with the PSR-3 logger injected. That makes the swap to league/csv plus a custom flattener — or to a vendored fork — a one-class change. If we already hand-roll json_decode/fputcsv, migrate one export path at a time and diff outputs against golden fixtures before cutting over.

Compatibility. Lock keboola/php-temp and keboola/php-utils transitively via composer.lock; these are the pieces most likely to fight our PHP version or filesystem assumptions. The parser wants real filesystem paths, not Flysystem disks — bridge with Storage::path(); remote disks (S3) require local staging then upload. Confirm behavior on Windows/CI runners if the pipeline is cross-platform.

Sequencing. (1) Spike against three representative production payloads and capture exact CSV output, including the array-vs-CSV API question; (2) agree the flattening contract (headers, ordering, child tables, link columns) with downstream consumers; (3) build adapter + contract + provider binding + config file (temp path, delimiter, enclosure, type-inference toggles); (4) golden-file contract tests around our real payloads; (5) move execution into queued jobs with temp-file cleanup in finally or a terminating hook; (6) add observability — row counts, file sizes, duration, temp-dir usage; (7) document the fallback and pin the version with a ^ ceiling.

Operational Impact

Maintenance. Low churn, high ownership burden. Recent release (2024-07-30) but almost no external usage history, so we carry the upgrade-review cost ourselves. Budget for periodic manual review and a pre-agreed decision to fork rather than wait on upstream. Track CVEs on the transitive Keboola dependencies, not just the parser.

Support. No vendor SLA unless we hold a Keboola contract; GitHub issues are the only channel. Internally designate one engineer as owner and write a one-page runbook covering output schema, temp-file locations, cleanup behavior, and known flattening quirks — otherwise the semantics live only in the head of whoever ran the spike.

Scaling. Scales horizontally by adding queue workers, since work is file-based rather than request-bound. A single very large JSON document remains memory-bound during decode — plan to chunk input as arrays-of-records rather than parse monolithic documents, and to split output into multiple CSVs by size. Watch disk and inode consumption on the temp volume; schedule cleanup for orphaned files.

Failure modes. Malformed JSON → exceptions requiring a typed wrapper and a dead-letter queue. Heterogeneous arrays → inconsistent or exploding columns that silently break downstream imports. Type inference → stripped leading zeros, precision loss on large integers, locale/format surprises. Temp exhaustion or worker crash mid-write → truncated CSVs; require atomic write-then-move. CSV/formula injection → sanitize cells starting with =, +, -, @. Encoding issues on non-UTF-8 or BOM-prefixed input.

Ramp-up. The API surface is small — a mid-level engineer is productive in a day — but genuinely understanding the flattening and type-coercion rules takes longer and is best captured as executable golden tests rather than prose. The dominant onboarding cost is not the library; it is the surrounding pipeline: queueing, temp storage, cleanup, and the downstream schema contract.