diff options
Diffstat (limited to 'includes/json')
| -rw-r--r-- | includes/json/FormatJson.php | 20 | ||||
| -rw-r--r-- | includes/json/JsonUnserializable.php | 48 | ||||
| -rw-r--r-- | includes/json/JsonUnserializableTrait.php | 50 | ||||
| -rw-r--r-- | includes/json/JsonUnserializer.php | 107 |
4 files changed, 221 insertions, 4 deletions
diff --git a/includes/json/FormatJson.php b/includes/json/FormatJson.php index 4ee709fe9949..409a1cc032c9 100644 --- a/includes/json/FormatJson.php +++ b/includes/json/FormatJson.php @@ -20,6 +20,8 @@ * @file */ +use MediaWiki\Json\JsonUnserializable; + /** * JSON formatter wrapper class */ @@ -328,11 +330,13 @@ class FormatJson { * * * @param mixed $value + * @param bool $expectUnserialize * @param string $accumulatedPath * @return string|null JSON path to first encountered non-serializable property or null. */ private static function detectNonSerializableDataInternal( $value, + bool $expectUnserialize, string $accumulatedPath ): ?string { if ( is_array( $value ) || @@ -340,13 +344,19 @@ class FormatJson { foreach ( $value as $key => $propValue ) { $propValueNonSerializablePath = self::detectNonSerializableDataInternal( $propValue, + $expectUnserialize, $accumulatedPath . '.' . $key ); if ( $propValueNonSerializablePath ) { return $propValueNonSerializablePath; } } - // Instances of classes other the \stdClass can not be serialized to JSON + } elseif ( ( $expectUnserialize && $value instanceof JsonUnserializable ) + // Trust that JsonSerializable will correctly serialize. + || ( !$expectUnserialize && $value instanceof JsonSerializable ) + ) { + return null; + // Instances of classes other the \stdClass or JsonSerializable can not be serialized to JSON. } elseif ( !is_scalar( $value ) && $value !== null ) { return $accumulatedPath; } @@ -357,11 +367,13 @@ class FormatJson { * Checks if the $value is JSON-serializable (contains only scalar values) * and returns a JSON-path to the first non-serializable property encountered. * - * @since 1.36 * @param mixed $value + * @param bool $expectUnserialize whether to expect the $value to be unserializable with JsonUnserializer. * @return string|null JSON path to first encountered non-serializable property or null. + * @see \MediaWiki\Json\JsonUnserializer + * @since 1.36 */ - public static function detectNonSerializableData( $value ): ?string { - return self::detectNonSerializableDataInternal( $value, '$' ); + public static function detectNonSerializableData( $value, bool $expectUnserialize = false ): ?string { + return self::detectNonSerializableDataInternal( $value, $expectUnserialize, '$' ); } } diff --git a/includes/json/JsonUnserializable.php b/includes/json/JsonUnserializable.php new file mode 100644 index 000000000000..cdfe2ba19799 --- /dev/null +++ b/includes/json/JsonUnserializable.php @@ -0,0 +1,48 @@ +<?php +/** + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License along + * with this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + * http://www.gnu.org/copyleft/gpl.html + * + * @file + * @ingroup Json + */ + +namespace MediaWiki\Json; + +use JsonSerializable; + +/** + * Classes implementing this interface support round-trip JSON serialization/unserialization + * using the JsonUnserializer utility. + * + * The resulting JSON must be annotated with class information for unserialization to work. + * Use JsonUnserializableTrait in implementing classes which annotates the JSON automatically. + * + * @see JsonUnserializer + * @see JsonUnserializableTrait + * @since 1.36 + * @package MediaWiki\Json + */ +interface JsonUnserializable extends JsonSerializable { + + /** + * Creates a new instance of the class and initialized it from the $json array. + * @param JsonUnserializer $unserializer an instance of JsonUnserializer to use + * for nested properties if they need special care. + * @param array $json + * @return JsonUnserializable + */ + public static function newFromJsonArray( JsonUnserializer $unserializer, array $json ); +} diff --git a/includes/json/JsonUnserializableTrait.php b/includes/json/JsonUnserializableTrait.php new file mode 100644 index 000000000000..8f757bbfe1c3 --- /dev/null +++ b/includes/json/JsonUnserializableTrait.php @@ -0,0 +1,50 @@ +<?php +/** + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License along + * with this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + * http://www.gnu.org/copyleft/gpl.html + * + * @file + * @ingroup Json + */ + +namespace MediaWiki\Json; + +trait JsonUnserializableTrait { + + public function jsonSerialize() { + return $this->annotateJsonForDeserialization( + $this->toJsonArray() + ); + } + + /** + * Annotate the $json array with class metadata. + * + * @param array $json + * @return array + */ + private function annotateJsonForDeserialization( array $json ) : array { + $json[JsonUnserializer::TYPE_ANNOTATION] = get_class( $this ); + return $json; + } + + /** + * Prepare this object for JSON serialization. + * The returned array will be passed to self::newFromJsonArray + * upon JSON deserialization. + * @return array + */ + abstract protected function toJsonArray(): array; +} diff --git a/includes/json/JsonUnserializer.php b/includes/json/JsonUnserializer.php new file mode 100644 index 000000000000..c47f4aa78215 --- /dev/null +++ b/includes/json/JsonUnserializer.php @@ -0,0 +1,107 @@ +<?php +/** + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License along + * with this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + * http://www.gnu.org/copyleft/gpl.html + * + * @file + * @ingroup Json + */ + +namespace MediaWiki\Json; + +use FormatJson; +use InvalidArgumentException; + +/** + * Helper class to unserialize instances of JsonUnserializable. + * + * @package MediaWiki\Json + */ +class JsonUnserializer { + + /** + * Name of the property where the class information is stored. + * @internal + */ + public const TYPE_ANNOTATION = '_type_'; + + /** + * Restore an instance of JsonUnserializable subclass from the JSON serialization. + * + * @param array|string|object $json + * @param string|null $expectedClass What class to expect in unserialization. If null, no expectation. + * @throws InvalidArgumentException if the passed $json can't be unserialized. + * @return JsonUnserializable + */ + public function unserialize( $json, string $expectedClass = null ) : JsonUnserializable { + if ( is_string( $json ) ) { + $json = FormatJson::decode( $json, true ); + if ( !$json ) { + // TODO: in PHP 7.3, we can use JsonException + throw new InvalidArgumentException( 'Bad JSON' ); + } + } + + if ( is_object( $json ) ) { + $json = (array)$json; + } + + if ( !$this->canMakeNewFromValue( $json ) ) { + throw new InvalidArgumentException( 'JSON did not have ' . self::TYPE_ANNOTATION ); + } + + $class = $json[self::TYPE_ANNOTATION]; + if ( !class_exists( $class ) || !is_subclass_of( $class, JsonUnserializable::class ) ) { + throw new InvalidArgumentException( "Target class {$class} does not exist" ); + } + + $obj = $class::newFromJsonArray( $this, $json ); + + // Check we haven't accidentally unserialized a godzilla if we were told we are not expecting it. + if ( $expectedClass && !is_a( $obj, $expectedClass ) ) { + $actualClass = get_class( $obj ); + throw new InvalidArgumentException( "Expected {$expectedClass}, got {$actualClass}" ); + } + return $obj; + } + + /** + * Helper to unserialize an array of JsonUnserializable instances or scalars. + * @param array $array + * @return array + */ + public function unserializeArray( array $array ) : array { + $unserializedExtensionData = []; + foreach ( $array as $key => $value ) { + if ( $this->canMakeNewFromValue( $value ) ) { + $unserializedExtensionData[$key] = $this->unserialize( $value ); + } else { + $unserializedExtensionData[$key] = $value; + } + } + return $unserializedExtensionData; + } + + /** + * Is it likely possible to make a new instance from $json serialization? + * @param mixed $json + * @return bool + */ + private function canMakeNewFromValue( $json ) : bool { + $classAnnotation = self::TYPE_ANNOTATION; + return ( is_array( $json ) && array_key_exists( $classAnnotation, $json ) ) || + ( is_object( $json ) && isset( $json->$classAnnotation ) ); + } +} |