Json Laravel Package

Getting Started

Install the package with composer require ergebnis/json, then start using the Ergebnis\Json\Json value object to represent validated JSON strings. The primary use case is to enforce that any JSON string in your domain (e.g., config payloads, API responses, event payloads) has already been validated and is structurally correct — preventing accidental use of malformed JSON later in your application. For example:

use Ergebnis\Json\Json;

$json = Json::fromString('{"status":"ok"}'); // safe: throws if invalid
echo $json->toString(); // '{"status":"ok"}'

Begin by reading the README.md, which provides all essential examples (from string, from file, exception types), and check the CHANGELOG for version-specific changes affecting PHP version support and APIs.

Implementation Patterns

Typical workflows include:

• Value Object encapsulation: Wrap incoming JSON payloads (e.g., from HTTP requests, CLI arguments, or消息 queues) immediately after decoding validation to ensure only valid JSON propagates.
• Type safety in DTOs/Value Objects: Declare constructor parameters as Json\Json instead of string or mixed to enforce contract integrity at the type level.
• File-backed JSON handling: Use Json::fromFile() for safe, early validation of local JSON files (e.g., config.json, package.json), letting exceptions surface issues before runtime.
• Integration with PSR-7/15/17: In middleware or controllers, convert validated JSON to Json\Json after checking Content-Type, then pass to domain services.
• Testing: Use Json::fromString($expectedJson) in unit tests to assert equality between actual and expected payloads (value objects implement strict identity and value semantics).

You can extract associative arrays or objects for further processing using json_decode($json->toString(), true) when needed, but prefer keeping Json instances at boundaries and decoding only at the edges.

Gotchas and Tips

• PHP version compatibility: Check the changelog carefully — support for newer PHP versions (e.g., 8.3, 8.4, 8.5) was added incrementally, and some older releases dropped 8.0 support unexpectedly. Use the latest stable release to ensure broad compatibility.
• Always decode to object internally: Internally, decoding to object (not array) is guaranteed (since v1.0.1), but when you manually decode after extraction, be explicit: json_decode($json->toString(), false) to avoid unintended behavior.
• Exception granularity matters: Exceptions like NotJson, FileDoesNotExist, FileCanNotBeRead, and FileDoesNotContainJson let you differentiate failure modes cleanly. Don’t catch generic Exception — handle each case appropriately.
• No decoding/validation logic inside the object: This is not a decoder — it’s a validated string wrapper. It does not parse, normalize, or pretty-print. Combine with json_encode, json_decode, or ergebnis/json-normalizer for richer workflows.
• String casts are implicit: Json implements __toString(), so echo $json just works, but in strcmp() or strict comparisons, rely on $json->toString() for consistency.
• Avoid storing in sessions/cache without re-validation: Since this is just a string wrapper, if your session or cache layer mutates the JSON (e.g., via serialization), verify integrity on retrieval — the object doesn’t protect against external corruption.
• Minimal but intentional API: Only fromString(), fromFile(), toString(), and __toString() exist — embrace the discipline of no optional parameters or default behavior. If you need normalization, use json-normalizer, which depends on this package.