<?php

declare(strict_types=1);

namespace App\Support\Json;

/**
 * Canonical JSON encoding for byte-stable storage.
 *
 * MySQL 8.0 JSON columns may reorder associative-array keys on
 * round-trip. For values that need byte-stability (schema snapshots,
 * webhook payloads signed via HMAC, audit-replay diffs), canonicalize
 * the structure before encode so re-emits produce identical bytes.
 *
 * Strategy:
 * - Associative arrays: recursively ksort
 * - Numeric-indexed lists (`array_is_list()`): preserve order
 *   (semantically ordered)
 * - Scalars and non-arrays: passthrough
 *
 * Numeric vs associative detection follows array_is_list() — PHP 8.1+
 * convention. Mixed-key arrays are treated as associative (rare and
 * indicative of a data issue worth surfacing rather than papering over).
 *
 * RFC-WS-6 session 2.7 — see also CLAUDE.md "Database" section
 * (byte-stability rule for JSON columns).
 */
final class JsonCanonicalizer
{
    /**
     * Canonicalize the structure recursively (sort associative keys).
     *
     * @template T
     *
     * @param  T  $value
     * @return T
     */
    public static function canonicalize(mixed $value): mixed
    {
        if (! is_array($value)) {
            return $value;
        }

        if ($value === []) {
            return $value;
        }

        if (array_is_list($value)) {
            return array_map(self::canonicalize(...), $value);
        }

        ksort($value);
        foreach ($value as $key => $child) {
            $value[$key] = self::canonicalize($child);
        }

        return $value;
    }

    /**
     * Encode a value as canonical JSON.
     *
     * Use for values stored in MySQL JSON columns where byte-stability
     * matters across reads/writes.
     *
     * @throws \JsonException
     */
    public static function encode(mixed $value): string
    {
        return json_encode(
            self::canonicalize($value),
            JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_THROW_ON_ERROR,
        );
    }
}