Safe ParserOutput extension data and JsonUnserializable helper.

One major difference with what we've had before is that now we
actually write class names into the serialization - given that
this new mechanism is extencible, we can't establish any kind
of mapping of allowed classes. I do not think it's a problem
though.

Bug: T264394
Change-Id: Ia152f3b76b967aabde2d8a182e3aec7d3002e5ea

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 ) );
+	}
+}