Json5 Laravel Package

Getting Started

Install via Composer:

composer require colinodell/json5

Start by parsing a simple JSON5 config file—e.g., config.json5 with comments and unquoted keys:

use ColinODell\Json5\Parser;

$parser = new Parser();
$config = $parser->decode(file_get_contents('config.json5'));
// $config is now a standard PHP array or object

First use case: replace config.php or config.json with config.json5 for a more readable config file while retaining type safety on decode.

Implementation Patterns

• Configuration Loading: Use decode() to load .json5 config files (e.g., config/database.json5) and inject parsed data into services. Ideal for CLI tools or microframeworks where developer ergonomics matter.
• API Input Validation: Accept JSON5 payloads from trusted internal tools—e.g., admin UIs or migration scripts—then convert to strict JSON for downstream systems:

  $json5 = file_get_contents('php://input');
  $data = $parser->decode($json5);
  // Convert to JSON if storing in Redis, sending to external API, etc.
  $json = $parser->encode($data); // guarantees valid JSON output
  

• Custom File Extensions: Bind .json5 to json5 mime type in web servers (e.g., Nginx types { application/json5 json5; }) and use middleware to auto-parse before controllers.
• Testing with Human-Readable Data: In tests, embed small JSON5 fixtures inline (e.g., $fixture = $parser->decode('{"foo": "bar", // comment\n}');) for clarity.

Gotchas and Tips

• No JSON_THROW_ON_ERROR Integration: Errors throw Json5DecodeException (not JsonException). Always wrap decode() in try/catch and inspect $e->getMessage() for precise line/column info.
• Decode Context Matters: decode() returns associative arrays by default (like json_decode(..., true)). Use decode(..., $assoc = false) if you prefer objects.
• Precision & Floats: JSON5 supports hex integers (e.g., 0xFF) and unquoted numeric keys—but ensure downstream systems handle non-base-10 integers (e.g., database schemas expect strings or cast explicitly).
• Trailing Commas Are Always Allowed: Even in object literals like {a: 1, b: 2,}—this differs from strict JSON but can trip up IDE linters. Disable JSON validation in tools if editing .json5 files.
• Extensibility: The parser supports Json5DecoderInterface—you can swap implementations for custom behavior (e.g., logging warnings for relaxed syntax).
• Performance: Not a bottleneck for config loads, but avoid parsing 100KB+ files in hot paths—decode() is ~2x slower than json_decode() due to additional parsing rules.