diff options
Diffstat (limited to 'includes/json/JsonCodec.php')
| -rw-r--r-- | includes/json/JsonCodec.php | 293 |
1 files changed, 158 insertions, 135 deletions
diff --git a/includes/json/JsonCodec.php b/includes/json/JsonCodec.php index aff96469fbfc..5331b255508d 100644 --- a/includes/json/JsonCodec.php +++ b/includes/json/JsonCodec.php @@ -21,11 +21,15 @@ namespace MediaWiki\Json; +use InvalidArgumentException; use JsonException; use JsonSerializable; -use MediaWiki\Parser\ParserOutput; +use Psr\Container\ContainerInterface; +use ReflectionClass; use stdClass; use Wikimedia\Assert\Assert; +use Wikimedia\JsonCodec\JsonClassCodec; +use Wikimedia\JsonCodec\JsonCodecable; /** * Helper class to serialize/deserialize things to/from JSON. @@ -34,7 +38,103 @@ use Wikimedia\Assert\Assert; * @since 1.36 * @package MediaWiki\Json */ -class JsonCodec implements JsonDeserializer, JsonSerializer { +class JsonCodec + extends \Wikimedia\JsonCodec\JsonCodec + implements JsonDeserializer, JsonSerializer +{ + + /** + * When true, add extra properties to the serialized output for + * backwards compatibility. This will eventually be made a + * configuration variable and/or removed. (T367584) + */ + private bool $backCompat = true; + + /** + * Create a new JsonCodec, with optional access to the provided services. + */ + public function __construct( ?ContainerInterface $services = null ) { + parent::__construct( $services ); + } + + /** + * Support the JsonCodecable interface by maintaining a mapping of + * class names to codecs. + * @param class-string $className + * @return ?JsonClassCodec + */ + protected function codecFor( string $className ): ?JsonClassCodec { + static $deserializableCodec = null; + static $serializableCodec = null; + $codec = parent::codecFor( $className ); + if ( $codec !== null ) { + return $codec; + } + // Resolve class aliases to ensure we don't use split codecs + $className = ( new ReflectionClass( $className ) )->getName(); + // Provide a codec for JsonDeserializable objects + if ( is_a( $className, JsonDeserializable::class, true ) ) { + if ( $deserializableCodec === null ) { + $deserializableCodec = new JsonDeserializableCodec( $this ); + } + $codec = $deserializableCodec; + $this->addCodecFor( $className, $codec ); + return $codec; + } + // Provide a codec for JsonSerializable objects: + // NOTE this is for compatibility only and does not deserialize! + if ( is_a( $className, JsonSerializable::class, true ) ) { + $codec = JsonSerializableCodec::getInstance(); + $this->addCodecFor( $className, $codec ); + return $codec; + } + return null; + } + + /** @inheritDoc */ + protected function markArray( array &$value, string $className, ?string $classHint ): void { + parent::markArray( $value, $className, $classHint ); + // Temporarily for backward compatibility add COMPLEX_ANNOTATION as well + if ( $this->backCompat ) { + $value[JsonConstants::COMPLEX_ANNOTATION] = true; + if ( ( $value[JsonConstants::TYPE_ANNOTATION] ?? null ) === 'array' ) { + unset( $value[JsonConstants::TYPE_ANNOTATION] ); + } + } + } + + /** @inheritDoc */ + protected function isArrayMarked( array $value ): bool { + // Temporarily for backward compatibility look for COMPLEX_ANNOTATION as well + if ( $this->backCompat && array_key_exists( JsonConstants::COMPLEX_ANNOTATION, $value ) ) { + return true; + } + if ( ( $value['_type_'] ?? null ) === 'string' ) { + // T313818: see ParserOutput::detectAndEncodeBinary() + return false; + } + return parent::isArrayMarked( $value ); + } + + /** @inheritDoc */ + protected function unmarkArray( array &$value, ?string $classHint ): string { + // Temporarily use the presence of COMPLEX_ANNOTATION as a hint that + // the type is 'array' + if ( + $this->backCompat && + $classHint === null && + array_key_exists( JsonConstants::COMPLEX_ANNOTATION, $value ) + ) { + $classHint = 'array'; + } + // @phan-suppress-next-line PhanUndeclaredClassReference 'array' + $className = parent::unmarkArray( $value, $classHint ); + // Remove the temporarily-added COMPLEX_ANNOTATION + if ( $this->backCompat ) { + unset( $value[JsonConstants::COMPLEX_ANNOTATION] ); + } + return $className; + } /** @deprecated since 1.43; use ::deserialize() */ public function unserialize( $json, ?string $expectedClass = null ) { @@ -44,8 +144,10 @@ class JsonCodec implements JsonDeserializer, JsonSerializer { public function deserialize( $json, string $expectedClass = null ) { Assert::parameterType( [ 'stdClass', 'array', 'string' ], $json, '$json' ); Assert::precondition( - !$expectedClass || is_subclass_of( $expectedClass, JsonDeserializable::class ), - '$expectedClass parameter must be subclass of JsonDeserializable, got ' . $expectedClass + !$expectedClass || + is_subclass_of( $expectedClass, JsonDeserializable::class ) || + is_subclass_of( $expectedClass, JsonCodecable::class ), + '$expectedClass parameter must be subclass of JsonDeserializable or JsonCodecable, got ' . $expectedClass ); if ( is_string( $json ) ) { $jsonStatus = FormatJson::parse( $json, FormatJson::FORCE_ASSOC ); @@ -59,39 +161,32 @@ class JsonCodec implements JsonDeserializer, JsonSerializer { $json = (array)$json; } - if ( $this->containsComplexValue( $json ) ) { - // Recursively deserialize the array values before deserializing - // the array itself. - $json = $this->deserializeArray( $json ); - } - - if ( !$this->canMakeNewFromValue( $json ) ) { - if ( $expectedClass ) { - throw new JsonException( 'JSON did not have ' . JsonConstants::TYPE_ANNOTATION ); + if ( $expectedClass !== null ) { + // Make copy of $json to avoid unmarking the 'real thing' + $jsonCopy = $json; + if ( is_array( $jsonCopy ) && $this->isArrayMarked( $jsonCopy ) ) { + $got = $this->unmarkArray( $jsonCopy, $expectedClass ); + // Compare $got to $expectedClass in a way that works in the + // presence of aliases + if ( is_a( $got, $expectedClass, true ) ) { + // Everything ok! + } else { + throw new JsonException( "Expected {$expectedClass} got {$got}" ); + } + } else { + $got = get_debug_type( $json ); + throw new JsonException( "Expected {$expectedClass} got {$got}" ); } - return $json; - } - - $class = $json[JsonConstants::TYPE_ANNOTATION]; - if ( $class == "ParserOutput" || $class == "MediaWiki\\Parser\\ParserOutput" ) { - $class = ParserOutput::class; // T353835 - } elseif ( $class !== stdClass::class && - !( class_exists( $class ) && is_subclass_of( $class, JsonDeserializable::class ) ) - ) { - throw new JsonException( "Invalid target class {$class}" ); } - - if ( $expectedClass && $class !== $expectedClass && !is_subclass_of( $class, $expectedClass ) ) { - throw new JsonException( - "Refusing to deserialize: expected $expectedClass, got $class" - ); + try { + $result = is_array( $json ) ? $this->newFromJsonArray( $json ) : $json; + } catch ( InvalidArgumentException $e ) { + throw new JsonException( $e->getMessage() ); } - - unset( $json[JsonConstants::TYPE_ANNOTATION] ); - if ( $class === stdClass::class ) { - return (object)$json; + if ( $expectedClass && !is_a( $result, $expectedClass, false ) ) { + throw new JsonException( "Unexpected class: {$expectedClass}" ); } - return $class::newFromJsonArray( $this, $json ); + return $result; } /** @deprecated since 1.43; use ::deserializeArray() */ @@ -100,79 +195,23 @@ class JsonCodec implements JsonDeserializer, JsonSerializer { } public function deserializeArray( array $array ): array { - $deserializedExtensionData = []; - foreach ( $array as $key => $value ) { - if ( $key === JsonConstants::COMPLEX_ANNOTATION ) { - /* don't include this in the result */ - } elseif ( - $this->canMakeNewFromValue( $value ) || - $this->containsComplexValue( $value ) - ) { - $deserializedExtensionData[$key] = $this->deserialize( $value ); - } else { - $deserializedExtensionData[$key] = $value; - } - } - return $deserializedExtensionData; - } - - private function serializeOne( &$value ) { - if ( $value instanceof JsonSerializable ) { - $value = $value->jsonSerialize(); - if ( !is_array( $value ) ) { - // Although JsonSerializable doesn't /require/ the result to be - // an array, JsonCodec and JsonDeserializableTrait do. - throw new JsonException( "jsonSerialize didn't return array" ); - } - $value[JsonConstants::COMPLEX_ANNOTATION] = true; - // The returned array may still have instance of JsonSerializable, - // stdClass, or array, so fall through to recursively handle these. - } elseif ( is_object( $value ) && get_class( $value ) === stdClass::class ) { - // T312589: if $value is stdObject, mark the type - // so we deserialize as stdObject as well. - $value = (array)$value; - $value[JsonConstants::TYPE_ANNOTATION] = stdClass::class; - $value[JsonConstants::COMPLEX_ANNOTATION] = true; - // Fall through to handle the property values - } - if ( is_array( $value ) ) { - $is_complex = false; - // Recursively convert array values to serializable form - foreach ( $value as &$v ) { - if ( is_object( $v ) || is_array( $v ) ) { - $v = $this->serializeOne( $v ); - if ( isset( $v[JsonConstants::COMPLEX_ANNOTATION] ) ) { - $is_complex = true; - } - } - } - if ( $is_complex ) { - $value[JsonConstants::COMPLEX_ANNOTATION] = true; - } - } elseif ( !is_scalar( $value ) && $value !== null ) { - $details = get_debug_type( $value ); - throw new JsonException( - 'Unable to serialize JSON: ' . $details - ); + try { + // Pass a class hint here to ensure we recurse into the array. + // @phan-suppress-next-line PhanUndeclaredClassReference 'array' + return $this->newFromJsonArray( $array, 'array' ); + } catch ( InvalidArgumentException $e ) { + throw new JsonException( $e->getMessage() ); } - return $value; } public function serialize( $value ) { - // Detect if the array contained any properties non-serializable - // to json. - // TODO: make detectNonSerializableData not choke on cyclic structures. - $deserializablePath = $this->detectNonSerializableDataInternal( - $value, false, '$', false - ); - if ( $deserializablePath ) { - throw new JsonException( - "Non-deserializable property set at {$deserializablePath}" - ); - } - // Recursively convert stdClass and JsonSerializable + // Recursively convert stdClass, JsonSerializable, and JsonCodecable // to serializable arrays - $value = $this->serializeOne( $value ); + try { + $value = $this->toJsonArray( $value ); + } catch ( InvalidArgumentException $e ) { + throw new JsonException( $e->getMessage() ); + } // Format as JSON $json = FormatJson::encode( $value, false, FormatJson::ALL_OK ); if ( !$json ) { @@ -192,37 +231,9 @@ class JsonCodec implements JsonDeserializer, JsonSerializer { return $json; } - /** - * Is it likely possible to make a new instance from $json serialization? - * @param mixed $json - * @return bool - */ - private function canMakeNewFromValue( $json ): bool { - $classAnnotation = JsonConstants::TYPE_ANNOTATION; - if ( is_array( $json ) ) { - return array_key_exists( $classAnnotation, $json ) && - # T313818: conflict with ParserOutput::detectAndEncodeBinary() - $json[$classAnnotation] !== 'string'; - } - - if ( is_object( $json ) ) { - return property_exists( $json, $classAnnotation ); - } - return false; - } - - /** - * Does this serialized array contain a complex value (a serialized class - * or an array which itself contains a serialized class)? - * @param mixed $json - * @return bool - */ - private function containsComplexValue( $json ): bool { - if ( is_array( $json ) ) { - return array_key_exists( JsonConstants::COMPLEX_ANNOTATION, $json ); - } - return false; - } + // The code below this point is used only for diagnostics; in particular + // for the ::detectNonSerializableData() method which is used to provide + // debugging information in the event of a serialization failure. /** * Recursive check for ability to serialize $value to JSON via FormatJson::encode(). @@ -241,8 +252,8 @@ class JsonCodec implements JsonDeserializer, JsonSerializer { bool $exhaustive = false ): ?string { if ( - $this->canMakeNewFromValue( $value ) || - $this->containsComplexValue( $value ) + ( is_array( $value ) && $this->isArrayMarked( $value ) ) || + ( $value instanceof stdClass && $this->isArrayMarked( (array)$value ) ) ) { // Contains a conflicting use of JsonConstants::TYPE_ANNOTATION or // JsonConstants::COMPLEX_ANNOTATION; in the future we might use @@ -252,6 +263,17 @@ class JsonCodec implements JsonDeserializer, JsonSerializer { if ( is_object( $value ) ) { if ( get_class( $value ) === stdClass::class ) { $value = (array)$value; + } elseif ( $value instanceof JsonCodecable ) { + if ( $exhaustive ) { + // Call the appropriate serialization method and recurse to + // ensure contents are also serializable. + $codec = $this->codecFor( get_class( $value ) ); + $value = $codec->toJsonArray( $value ); + } else { + // Assume that serializable objects contain 100% + // serializable contents in their representation. + return null; + } } elseif ( $expectDeserialize ? $value instanceof JsonDeserializable : @@ -260,6 +282,7 @@ class JsonCodec implements JsonDeserializer, JsonSerializer { if ( $exhaustive ) { // Call the appropriate serialization method and recurse to // ensure contents are also serializable. + '@phan-var JsonSerializable $value'; $value = $value->jsonSerialize(); if ( !is_array( $value ) ) { return $accumulatedPath . ": jsonSerialize didn't return array"; @@ -271,7 +294,7 @@ class JsonCodec implements JsonDeserializer, JsonSerializer { } } else { // Instances of classes other the \stdClass or JsonSerializable can not be serialized to JSON. - return $accumulatedPath . ': ' . get_class( $value ); + return $accumulatedPath . ': ' . get_debug_type( $value ); } } if ( is_array( $value ) ) { |