Refactor JSON state serialization (#777)

* Refactor JSON state serialization

* fix: satisfy json codec lint

---------

Co-authored-by: homeboy-ci[bot] <266378653+homeboy-ci[bot]@users.noreply.github.com>

Author: chubes4

inc/Storage/CleanupRunRepository.php

@@ -7,8 +7,14 @@
 
 namespace DataMachineCode\Storage;
 
+use DataMachineCode\Support\JsonCodec;
+
 defined('ABSPATH') || exit;
 
+if ( ! class_exists(JsonCodec::class) ) {
+	require_once dirname(__DIR__) . '/Support/JsonCodec.php';
+}
+
 class CleanupRunRepository {
 
 
@@ -188,13 +194,11 @@ private function decode_item( array $row ): array {
 	}
 
 	private function encode( mixed $value ): string {
-		$encoded = wp_json_encode($value, JSON_UNESCAPED_SLASHES);
-		return false === $encoded ? '{}' : $encoded;
+		return JsonCodec::encode_or_default($value, '{}', JSON_UNESCAPED_SLASHES);
 	}
 
 	private function decode( mixed $value ): array {
-		$decoded = json_decode( (string) $value, true);
-		return is_array($decoded) ? $decoded : array();
+		return JsonCodec::decode_array($value, array());
 	}
 
 	private function new_run_id(): string {

inc/Storage/WorktreeInventoryRepository.php

@@ -7,8 +7,14 @@
 
 namespace DataMachineCode\Storage;
 
+use DataMachineCode\Support\JsonCodec;
+
 defined('ABSPATH') || exit;
 
+if ( ! class_exists(JsonCodec::class) ) {
+	require_once dirname(__DIR__) . '/Support/JsonCodec.php';
+}
+
 class WorktreeInventoryRepository {
 
 
@@ -276,7 +282,7 @@ private function normalize_row( array $row ): array {
 			'size_bytes'          => isset($row['size_bytes']) ? ( null === $row['size_bytes'] ? null : (int) $row['size_bytes'] ) : null,
 			'cleanup_signal'      => $this->cleanup_signal($row, $metadata),
 			'missing_path'        => ! empty($row['missing_path']) ? 1 : 0,
-			'metadata'            => wp_json_encode($metadata),
+			'metadata'            => JsonCodec::encode_or_default($metadata),
 			'updated_at'          => current_time('mysql', true),
 		);
 	}
@@ -288,8 +294,7 @@ private function normalize_row( array $row ): array {
 	 * @return array<string,mixed>
 	 */
 	private function decode_row( array $row ): array {
-		$decoded         = isset($row['metadata']) && is_string($row['metadata']) ? json_decode($row['metadata'], true) : null;
-		$row['metadata'] = is_array($decoded) ? $decoded : null;
+		$row['metadata'] = isset($row['metadata']) && is_string($row['metadata']) ? JsonCodec::decode_array($row['metadata'], null) : null;
 		foreach ( array( 'id', 'is_primary', 'dirty_count', 'unpushed_count', 'artifact_count', 'artifact_size_bytes', 'size_bytes', 'missing_path' ) as $key ) {
 			if ( isset($row[ $key ]) ) {
 				$row[ $key ] = (int) $row[ $key ];

inc/Support/JsonCodec.php

@@ -0,0 +1,44 @@
+<?php
+/**
+ * Shared JSON encoding and decoding helpers.
+ *
+ * @package DataMachineCode\Support
+ */
+
+namespace DataMachineCode\Support;
+
+defined('ABSPATH') || exit;
+
+class JsonCodec {
+
+	/**
+	 * Encode a value as JSON.
+	 */
+	public static function encode( mixed $value, int $flags = 0, int $depth = 512 ): ?string {
+		$encoded = function_exists('wp_json_encode')
+			? wp_json_encode($value, $flags, $depth)
+			: json_encode($value, $flags, $depth); // phpcs:ignore WordPress.WP.AlternativeFunctions.json_encode_json_encode -- Portable fallback.
+
+		return is_string($encoded) ? $encoded : null;
+	}
+
+	/**
+	 * Encode a value as JSON, falling back to a caller-provided default on failure.
+	 */
+	public static function encode_or_default( mixed $value, string $fallback = '{}', int $flags = 0, int $depth = 512 ): string {
+		$encoded = self::encode($value, $flags, $depth);
+		return null === $encoded ? $fallback : $encoded;
+	}
+
+	/**
+	 * Decode a JSON object/array string, falling back to the supplied default.
+	 *
+	 * @param mixed             $value    JSON string.
+	 * @param array<mixed>|null $fallback Default returned when decoding fails or the result is not an array.
+	 * @return array<mixed>|null
+	 */
+	public static function decode_array( mixed $value, ?array $fallback = array() ): ?array {
+		$decoded = json_decode( (string) $value, true );
+		return is_array($decoded) ? $decoded : $fallback;
+	}
+}

inc/Workspace/WorkspaceCleanupPlan.php

@@ -7,8 +7,14 @@
 
 namespace DataMachineCode\Workspace;
 
+use DataMachineCode\Support\JsonCodec;
+
 defined('ABSPATH') || exit;
 
+if ( ! class_exists(JsonCodec::class) ) {
+	require_once dirname(__DIR__) . '/Support/JsonCodec.php';
+}
+
 if ( ! class_exists(WorktreeCleanupClassifier::class) ) {
 	require_once __DIR__ . '/WorktreeCleanupClassifier.php';
 }
@@ -780,8 +786,8 @@ private function stable_cleanup_row_id( string $type, array $row ): string {
 	 */
 	private function stable_cleanup_hash( mixed $value, string $prefix ): string {
 		$this->ksort_recursive($value);
-		$encoded = wp_json_encode($value, JSON_UNESCAPED_SLASHES);
-		if ( false === $encoded || '' === $encoded ) {
+		$encoded = JsonCodec::encode($value, JSON_UNESCAPED_SLASHES);
+		if ( null === $encoded || '' === $encoded ) {
 			$encoded = $prefix . '-json-error-' . json_last_error_msg();
 		}
 		return $prefix . '-' . substr(hash('sha256', $encoded), 0, 24);

tests/json-codec.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+if ( ! defined('ABSPATH') ) {
+	define('ABSPATH', __DIR__ . '/fixtures/');
+}
+
+require_once dirname(__DIR__) . '/inc/Support/JsonCodec.php';
+
+use DataMachineCode\Support\JsonCodec;
+
+function assert_same( mixed $expected, mixed $actual, string $message ): void {
+	if ( $expected !== $actual ) {
+		throw new RuntimeException(
+			sprintf(
+				"%s\nExpected: %s\nActual: %s",
+				$message,
+				var_export($expected, true),
+				var_export($actual, true)
+			)
+		);
+	}
+}
+
+assert_same(
+	'{"path":"foo/bar"}',
+	JsonCodec::encode_or_default(array( 'path' => 'foo/bar' ), '{}', JSON_UNESCAPED_SLASHES),
+	'Encodes with caller flags.'
+);
+assert_same(array( 'ok' => true ), JsonCodec::decode_array('{"ok":true}', array()), 'Decodes JSON arrays.');
+assert_same(array(), JsonCodec::decode_array('not-json', array()), 'Defaults invalid JSON to an empty array.');
+assert_same(null, JsonCodec::decode_array('not-json', null), 'Preserves nullable defaults.');
+
+print "json-codec OK\n";