Jsonrecast Laravel Package

Product Decisions This Supports

• Build vs. buy for "edit JSON in place" features. Any roadmap item that mutates a JSON document a user or another tool owns — composer.json, package.json, CI config, exported integration payloads, IaC parameter files — is a candidate. JsonRecast lets you do this in ~1 day instead of hand-rolling a tokenizer; the alternative (decode → mutate → json_encode) is 20 lines but destroys formatting and produces noisy diffs.
• Whether to ship "safe config editing" as a product capability. If your product touches customer-owned config files (a CLI, a dev-tool SaaS, a migration agent), diff noise is a support-ticket generator and a trust issue. Formatting-preserving writes convert "the tool mangled my file" into "the tool changed one line," which is a shippable quality bar, not a nice-to-have.
• Codemod / migration tooling. Visitor-based AST traversal is the right primitive for "find every *.json in this repo and rename key X, add field Y, or bump a version" without rewriting whitespace, key order, or indentation. This unlocks internal migration tooling and customer-facing upgrade assistants as a single investment.
• Scope decision on JSON5/JSONC/comments. The package targets JSON; if your users' files contain comments or trailing commas, this is a signal to scope the feature down (strict JSON only) rather than a signal to fork. Worth confirming during technical spike.
• Dependency posture / risk acceptance. 5 stars, 0 dependents, single-org provenance. Treat as a low-blast-radius dependency: fine to adopt behind an internal adapter interface, not fine to let its AST types leak into your domain model.
• Pricing/packaging input. If config-editing is bundled into an existing tier, this package is pure margin (MIT, no per-seat cost). If it enables a standalone "repo-aware migrations" SKU, this is the cheapest possible enabler of that revenue line.

When to Consider This Package

Adopt when most of these hold:

• Byte-level fidelity matters. The output file must remain reviewable in a PR — preserved indentation, key order, trailing newline, and existing whitespace.
• The JSON is not yours. You're editing files owned by the user or by another tool, where a full reformat is a visible, annoying side effect.
• You need structural traversal, not just a value lookup. "Visit every object that has key scripts" or "every string value under require" is awkward with json_decode + recursion and natural with a visitor.
• The write path is narrow and testable. You can wrap it in one adapter class with a small surface (parse, visit, mutate, print) so replacing it later is a contained change.
• You can tolerate PHP-version and strictness constraints. PHPStan level max and an active CI matrix are good signals, but pin the version and run your own compat check.

Look elsewhere — or use json_decode/json_encode — when:

• You don't need formatting preservation. Server-to-server payloads, internal queues, cache blobs: decode/mutate/encode is simpler, faster, and dependency-free.
• You need schema validation as a first-class feature. This is a parser/printer, not a validator; pair it with a schema library or you'll end up building validation yourself.
• You need JSON5/JSONC/comments, or YAML/TOML. Different problem; don't stretch this.
• You need a large, battle-tested ecosystem. 0 dependents and 5 stars means you are effectively an early adopter and a de facto QA partner. That's acceptable for a leaf-node utility, unacceptable on a critical path with no escape hatch.
• Throughput is the bottleneck. AST + visitor + round-trip printing will be slower and heavier than json_decode. Don't put it on a hot request path; use it in CLI, jobs, and editors.

How to Pitch It (Stakeholders)

To executives (one paragraph): A small, MIT-licensed PHP library that lets us edit JSON files programmatically while keeping the file byte-for-byte identical everywhere we didn't intentionally change. That means when our tool touches a customer's composer.json or config file, the pull request shows one changed line instead of a full-file rewrite — fewer support tickets, more trust, and a credible "safe, reviewable changes" story for any feature that writes into customer repos. Cost is essentially zero (MIT, no vendor lock-in) and it's quarantined behind our own interface, so the downside is limited to a few days of engineering if it doesn't work out. Risk to flag honestly: near-zero adoption today, so we'd be validating it ourselves and should treat it as a leaf dependency, not infrastructure.

To engineering (the ask): Spike it for two days against three real files from our repo — a composer.json, a CI workflow's JSON step, and a large exported payload. Success criteria: round-trip is a no-op on unmodified input, the visitor covers our "find and mutate nested keys" case without bespoke recursion, and PHP version/static-analysis constraints are compatible. Ship it behind a JsonEditor port with parse/mutate/print so a swap to a hand-rolled writer is a single-file change. Don't expose its AST types above the adapter, pin the version, and add a golden-file test suite that asserts byte-identical output on no-op edits.