Jsonreader Laravel Package

Product Decisions This Supports

• Build vs. buy for ingestion: A pull parser is the "buy" answer to "we need to process JSON files bigger than PHP's memory_limit." It replaces a bespoke parser, a jq subprocess, or a "just raise the limit / add more RAM" infrastructure workaround with a ~MIT-licensed Composer dependency.
• Feature scoping for large-data workflows: Unlocks or de-risks roadmap items like bulk import from third-party exports (commerce, banking, CRM, analytics dumps), webhook payload processing, log/event ingestion, and admin-side data migration — cases where the payload is measured in hundreds of MB and json_decode() would fatal or time out.
• Sync vs. async architecture: If a request can stream-parse as bytes arrive, a medium-large payload can stay in a synchronous job instead of forcing a queue, S3 staging bucket, and worker-size increase. That is a direct infrastructure-cost and time-to-market trade.
• Partial extraction as a product capability: Streaming lets you read only the fields you need and skip large embedded blobs (base64 attachments, image arrays, verbose nested objects). This supports "show me a preview of the import before committing" and "re-process one record without re-reading 2 GB" UX patterns.
• Error quality as a support-cost lever: Position-aware parse errors (byte offset / line information) let you return actionable messages to customers uploading malformed files, reducing support tickets and manual triage versus a generic json_decode failure.
• Peak-memory budgeting per plan tier: Knowing you can process a document in near-constant memory changes how you price or cap upload size, worker concurrency, and per-tenant resource limits — a pricing and capacity decision, not just an engineering one.
• Dependency risk acceptance: A 146-star package with a recent release (2025-11-11) but a small maintainer base is a "wrap it behind our own interface" decision, not a "call it from 40 places" decision.

When to Consider This Package

Adopt when most of these hold:

• Documents routinely exceed a few tens of MB, or peak memory during parsing is a real production constraint (queue workers, PHP-FPM pools, container limits).
• You need incremental consumption: time-to-first-record matters, you want progress reporting, or you must stream from a network socket or file handle rather than a string.
• You need only a subset of each document and want to skip the rest rather than materialize the whole tree.
• You want better parse diagnostics than json_decode() gives, or you need to validate while reading.
• You want an event/pull model (start/end/value tokens) rather than a callback or DOM-style API, and you are willing to own the small amount of state-machine code that consumes it.
• The maintainer's release cadence and PHP-version support match your platform, and you can wrap it behind your own JsonStreamReader-style interface.

Look elsewhere when:

• Payloads are small. Native json_decode() with JSON_THROW_ON_ERROR is faster (C vs. PHP), zero-dependency, and simpler. Do not add a parser to shave memory you do not need.
• You need random access, multiple passes, or a full in-memory tree — a pull parser is the wrong shape; keep the decoded structure.
• You need JSONPath/XPath-style querying, schema validation, or JSON Patch/Merge — pair with or choose opis/json, a JSONPath library, or a schema validator instead.
• Maximum throughput on small-to-medium documents is the goal; a pure-PHP tokenizer will lose to the C extension.
• Adoption/maintenance risk tolerance is low. At 146 stars this is a niche choice; halaxa/json-machine (streaming, much larger user base) and salsify/json-streaming-parser (event-based) are the mainstream comparisons. Benchmark all three against your real payloads before committing, and check the open-issue backlog, PHP 8.x coverage, and whether major versions have broken APIs historically.
• Your database can do it: MySQL JSON_TABLE, Postgres jsonb operators, or a jq pipeline may solve the problem with no PHP dependency at all.

How to Pitch It (Stakeholders)

To executives: We have a class of customer workflows — large imports, third-party data feeds, bulk exports — where our current approach either fails or forces us to buy bigger workers. A streaming JSON parser lets us process files far larger than memory in roughly constant footprint. That means we can ship the "large import" feature without a new service, without a queue-based re-architecture, and without raising infrastructure spend per tenant. It is a small MIT-licensed library: low cost, low lock-in, and we will isolate it behind our own interface so it is replaceable in days if needed. The main caveat is community size — this is a niche package, not a de facto standard — so the recommendation is adopt-with-a-wrapper, not adopt-everywhere.

To engineering: Event/token-based pull parser; you read() forward through the document and handle OBJECT_START, NAME, VALUE, ARRAY_END, and so on, so you never hold the full tree. Works from strings or streams, gives byte-offset error positions, and installs via Composer under MIT. Caveats to plan for: it is pure PHP, so it will not beat json_decode on small documents — use it only where memory or streaming actually matters; numeric values may surface as strings to preserve precision, so typed conversion is our code; and because we cannot assume long-term maintenance at this star count, we put it behind a thin adapter and add a benchmark/upgrade test so swapping to json-machine or salsify is a contained change. Ask: one spike against our real 200 MB+ payload to confirm memory ceiling and throughput before we commit it to the roadmap.