1	<?php
2	declare( strict_types=1 );
3
4	/**
5	* @license GPL-2.0-or-later
6	* @file
7	*/
8
9	namespace Wikimedia\JsonCodec;
10
11	/**
12	* Classes implementing this interface support round-trip JSON
13	* serialization/deserialization for certain class types.
14	* They may maintain state and/or consult service objects which
15	* are stored in the codec object.
16	*
17	* @template T
18	*/
19	interface JsonClassCodec {
20
21	/**
22	* Returns a JSON array representing the contents of the given object, that
23	* can be deserialized with the corresponding newFromJsonArray() method.
24	*
25	* The returned array can contain other JsonCodecables as values;
26	* the JsonCodec class will take care of encoding values in the array
27	* as needed, as well as annotating the returned array with the class
28	* information needed to locate the correct ::newFromJsonArray()
29	* method during deserialization.
30	*
31	* Only objects of the types registered to this JsonClassCodec will be
32	* provided to this method.
33	*
34	* @param T $obj An object of the type handled by this JsonClassCodec
35	* @return array A Json representation of the object.
36	*/
37	public function toJsonArray( $obj ): array;
38
39	/**
40	* Creates a new instance of the given class and initializes it from the
41	* $json array.
42	* @param class-string<T> $className
43	* @param array $json
44	* @return T
45	*/
46	public function newFromJsonArray( string $className, array $json );
47
48	/**
49	* Return an optional type hint for the given array key in the result of
50	* ::toJsonArray() / input to ::newFromJsonArray.  If a class name is
51	* returned here and it matches the runtime type of the value of that
52	* array key, then type information will be omitted from the generated
53	* JSON which can save space.  The class name can be suffixed with `[]`
54	* to indicate an array or list containing objects of the given class
55	* name.
56	*
57	* @param class-string<T> $className The class we're looking for a hint for
58	* @param string $keyName The name of the array key we'd like a hint on
59	* @return class-string|string|Hint|null A class string, Hint or null.
60	*   For backward compatibility, a class string suffixed with `[]` can
61	*   also be returned, but that is deprecated.
62	*/
63	public function jsonClassHintFor( string $className, string $keyName );
64	}