Jsonlint Laravel Package

Getting Started

1. Install the package with composer require seld/jsonlint.
2. Immediately import use Seld\JsonLint\JsonParser; and instantiate the parser.
3. Use lint() for quick validation (returns null if valid or a ParsingException with detailed diagnostics).
4. For structured validation plus parsing (like json_decode() but with better error context), use parse().
5. CLI usage: run vendor/bin/jsonlint config.json directly after install — no custom code needed for basic file linting.

Implementation Patterns

• Validation-then-decode pattern: Use json_decode($json) === false to detect failure, then fall back to $parser->lint() or $parser->parse() to surface precise error messages to users. This preserves performance while maintaining usability (as Composer does internally).
• Custom duplicate-key handling: For APIs or configuration files where duplicate keys are ambiguous, use JsonParser::DETECT_KEY_CONFLICTS to throw DuplicateKeyException, then extract line/key info via $e->getDetails().
• Relaxed parsing: Enable ALLOW_COMMENTS for dev-focused configs (e.g., config.dev.json with // or /* */ comments), but avoid in production for strict JSON compliance.
• Associative output: Prefer PARSE_TO_ASSOC when returning parsed data to templates or APIs expecting arrays over stdClass objects.

Gotchas and Tips

• Performance: Never use parse() as a drop-in json_decode() replacement. It is significantly slower—only invoke it when validation or rich error reporting is needed.
• Output safety: The CLI tool prints to STDERR by default. Use -q for quiet mode (e.g., in CI) to avoid polluting logs.
• Unicode & edge cases: While the library handles common edge cases (empty keys, UTF-8), truncated inputs and malformed Unicode escapes can still cause exceptions—always wrap parse() in try/catch for external/untrusted inputs.
• Flag combinations: Flags are bitwise; combine safely with | (e.g., PARSE_TO_ASSOC | ALLOW_COMMENTS). Ensure no flags conflict (though defaults are non-overlapping).
• Debugging: When using lint(), call getMessage() for developer-facing errors and getDetails() for programmatic context (line/column/key). In CLI, the output is already colorized and human-optimized—great for CI or pre-commit hooks.