Json Normalizer Laravel Package

Getting Started

Install the package with composer require ergebnis/json-normalizer. Begin by using the FormatNormalizer to enforce consistent JSON formatting (indentation, encoding options, newlines) across your project — ideal for ensuring composer.json, package.json, or custom config files follow team conventions. Check the README’s usage examples for quick start patterns; the ChainNormalizer is the most common first building block for multi-step normalization pipelines.

Implementation Patterns

• Pipeline Normalization: Use ChainNormalizer to compose generic normalizers (e.g., JsonEncodeNormalizer → IndentNormalizer → WithFinalNewLineNormalizer) for deterministic output. Order matters: apply encoding before pretty-printing.
• Custom Business Logic: Leverage CallableNormalizer to inject domain-specific rules (e.g., redact secrets, restructure nested arrays) while preserving the rest of the document structure.
• Schema-Driven Compliance: Use SchemaNormalizer to enforce structure and ordering (especially for composer.json) based on official JSON Schema. Combine with Pointer\Specification::equals() to exempt specific paths (e.g., custom plugins) from reordering.
• Vendor-Specific Automation: For PHP projects, rely on Vendor\Composer\ComposerJsonNormalizer as a drop-in for standardizing composer.json formatting, sorting, and validation — similar to what composer normalize does, but integrated into tooling or CI.

Gotchas and Tips

• Order Sensitivity: In ChainNormalizer, IndentNormalizer must run after JsonEncodeNormalizer, or indentation settings may be lost. Test your chain pipeline with varied inputs.
• Schema Normalizer Pitfalls: Properties not declared in the schema may be reordered or dropped depending on additionalProperties. Use Pointer\Specification (e.g., Specification::never() or Specification::equals(...)) to protect dynamic keys like extra sections.
• Encoding Gotchas: JsonEncodeNormalizer defaults to JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_HEX_AMP. Override with JsonEncodeOptions::fromInt(...) to avoid unnecessary escaping (e.g., JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE).
• Extensibility: Implement Normalizer\Normalizer to build custom normalizers — the interface is simple (normalize(Json $json): Json), making it easy to add project-specific rules.
• Validation Overhead: SchemaNormalizer validates before and after normalization. In CI/performance-sensitive workflows, consider skipping validation in production by using a lighter-weight normalizer chain or caching schema resolution.