Json Codec Laravel Package

Product Decisions This Supports

• API contract design and versioning. JsonCodec is a typed JSON serialization/deserialization layer: each class owns its own jsonSerialize() / newFromJson() behavior and fails loudly (typed exception) when an incoming payload doesn't match the expected shape. That makes it a useful lever when deciding where to enforce a contract — at the HTTP boundary on decode, rather than in scattered controller-level array poking.
• Build vs. buy for the serialization layer. The realistic alternative for most teams is "write our own typed hydrator." JsonCodec is a credible third option for narrow needs: small surface area, no transitive dependencies, no framework coupling. But it is not a replacement for a full serializer, so the decision is "adopt for one integration" rather than "standardize the codebase on this."
• Roadmap: Wikimedia/MediaWiki integration. If the roadmap includes consuming MediaWiki REST APIs, Parsoid, or other Wikimedia services, this is the codec their own services use. Adopting it reduces the risk of subtle semantic mismatches (type coercion, null handling, string-vs-object ambiguity) that you'd otherwise discover in production.
• Third-party ingestion and webhook contracts. Strict decode with explicit rejection and typed exceptions is a good fit for externally-authored payloads, where you want a clear "this payload is invalid" signal and a clean error path instead of silent coercion into a half-populated model.
• Licensing-driven distribution decisions. GPL-2.0 is a PM-level go/no-go, not a detail. For an internal service or SaaS (no distribution of the binary/source to customers), it is generally workable. For a distributed or on-prem product, it forces either a GPL-compatible posture or a hard no. Decide this before engineering spends a sprint on it.
• Opportunity signal, read honestly. The score (opportunity 54.11) suggests a real gap worth evaluating; the adoption signal (1 star, 0 dependents) says nobody in the PHP/Laravel ecosystem has validated it. That combination supports a time-boxed spike, not a roadmap commitment.

When to Consider This Package

Consider it when all of the following hold:

• You are integrating with Wikimedia/MediaWiki-family services and want serialization parity with the producer.
• You need strict, exception-based validation on decode with a small, dependency-free footprint and no framework coupling.
• GPL-2.0 is acceptable for your distribution model.
• Your team is willing to own thin glue code — there is no Laravel service provider, no config, no facades, no validation-rule integration.

Look elsewhere when:

• It's a standard Laravel API. Laravel's validation, Form Requests, and API Resources already cover request/response shaping with better DX, error messages, and authorization hooks.
• You need rich DTO ergonomics. Nested DTO graphs, casts, collections, attribute-based mapping, or OpenAPI generation point to spatie/laravel-data or symfony/serializer.
• You need schema-driven validation. OpenAPI/JSON Schema-first validation (league/openapi-psr7-validator, cebe/php-openapi) is a different and better fit than per-class codecs.
• You are shipping a proprietary distributed product. GPL-2.0 is the blocker.
• You need vendor support, docs, or an active issue tracker. The GitHub repo is an explicit read-only mirror of Gerrit; contributions and issue flow live in Wikimedia's Gerrit/Phabricator, on Wikimedia's priorities. Expect no roadmap influence, no response SLA, and no Laravel-idiomatic documentation.

How to Pitch It (Stakeholders)

To executives (one paragraph): We evaluated a small, dependency-free JSON codec maintained by Wikimedia. Its value is strict, typed validation of JSON at the service boundary — useful if we integrate with Wikimedia APIs, and a cheap way to make malformed external payloads fail fast instead of corrupting data downstream. The costs are equally clear: it is GPL-2.0 licensed, which is a real constraint if we ever distribute the product; it has essentially zero adoption outside Wikimedia (1 GitHub star, 0 dependents); and support follows Wikimedia's priorities, not ours. Recommendation: approve a short, time-boxed spike scoped to the specific integration, behind our own interface, with no commitment to broader adoption. If the licensing constraint is unacceptable, we stop there and lose little.

To engineering (one paragraph): JsonCodec gives you per-class jsonSerialize() / newFromJson() with strict type checking and a typed exception on mismatch. Zero transitive dependencies, no framework coupling, small enough to read in an afternoon. In exchange: no service provider, no config, no validation integration — you wire it by hand. The GitHub repo is a mirror; patches go to Gerrit, so treat it as a vendored dependency you may need to fork. Wrap it behind our own serialization interface so the swap cost stays near zero, and pin the version. Compare against spatie/laravel-data before writing any glue we'd have to maintain.