includes/json/JsonDeserializer.php

   1 <?php
   2
   3 /**
   4  * This program is free software; you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License as published by
   6  * the Free Software Foundation; either version 2 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License along
  15  * with this program; if not, write to the Free Software Foundation, Inc.,
  16  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  17  * http://www.gnu.org/copyleft/gpl.html
  18  *
  19  * @file
  20  * @ingroup Json
  21  */
  22
  23 namespace MediaWiki\Json;
  24
  25 use InvalidArgumentException;
  26
  27 /**
  28  * Deserializes things from JSON.
  29  *
  30  * @since 1.36
  31  * @package MediaWiki\Json
  32  */
  33 interface JsonDeserializer {
  34
  35         /**
  36          * Restore an instance of simple type or JsonDeserializable subclass
  37          * from the JSON serialization. It supports passing array/object to
  38          * allow manual decoding of the JSON string if needed.
  39          *
  40          * @note JSON objects are unconditionally deserialized as PHP associative
  41          * arrays, and not as instances of \stdClass.
  42          *
  43          * @phpcs:ignore MediaWiki.Commenting.FunctionComment.ObjectTypeHintParam
  44          * @param array|string|object $json
  45          * @param string|null $expectedClass What class to expect in deserialization.
  46          *   If null, no expectation. Must be a descendant of JsonDeserializable.
  47          * @throws InvalidArgumentException if the passed $json can't be deserialized.
  48          * @return mixed
  49          */
  50         public function deserialize( $json, ?string $expectedClass = null );
  51
  52         /**
  53          * Backwards-compatibility alias for deserialize()
  54          *
  55          * @deprecated since 1.43
  56          */
  57         public function unserialize( $json, ?string $expectedClass = null );
  58
  59         /**
  60          * Helper to deserialize an array of JsonDeserializable instances or simple types.
  61          * @param array $array
  62          * @return array
  63          */
  64         public function deserializeArray( array $array ): array;
  65
  66         /**
  67          * Backwards-compatibility alias for deserializeArray()
  68          *
  69          * @deprecated since 1.43
  70          */
  71         public function unserializeArray( array $array ): array;
  72 }
  73
  74 /** @deprecated class alias since 1.43 */
  75 class_alias( JsonDeserializer::class, 'MediaWiki\\Json\\JsonUnserializer' );