1	<?php
2	declare( strict_types=1 );
3
4	/**
5	* This program is free software; you can redistribute it and/or modify
6	* it under the terms of the GNU General Public License as published by
7	* the Free Software Foundation; either version 2 of the License, or
8	* (at your option) any later version.
9	*
10	* This program is distributed in the hope that it will be useful,
11	* but WITHOUT ANY WARRANTY; without even the implied warranty of
12	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13	* GNU General Public License for more details.
14	*
15	* You should have received a copy of the GNU General Public License along
16	* with this program; if not, write to the Free Software Foundation, Inc.,
17	* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18	* http://www.gnu.org/copyleft/gpl.html
19	*
20	* @file
21	*/
22
23	namespace Wikimedia\JsonCodec;
24
25	/**
26	* Classes implementing this interface support round-trip JSON
27	* serialization/deserialization for certain class types.
28	* They may maintain state and/or consult service objects which
29	* are stored in the codec object.
30	*
31	*
32	* @template T
33	*/
34	interface JsonClassCodec {
35
36	/**
37	* Returns a JSON array representing the contents of the given object, that
38	* can be deserialized with the corresponding newFromJsonArray() method.
39	*
40	* The returned array can contain other JsonCodecables as values;
41	* the JsonCodec class will take care of encoding values in the array
42	* as needed, as well as annotating the returned array with the class
43	* information needed to locate the correct ::newFromJsonArray()
44	* method during deserialization.
45	*
46	* Only objects of the types registered to this JsonClassCodec will be
47	* provided to this method.
48	*
49	* @param T $obj An object of the type handled by this JsonClassCodec
50	* @return array A Json representation of the object.
51	*/
52	public function toJsonArray( $obj ): array;
53
54	/**
55	* Creates a new instance of the given class and initializes it from the
56	* $json array.
57	* @param class-string<T> $className
58	* @param array $json
59	* @return T
60	*/
61	public function newFromJsonArray( string $className, array $json );
62
63	/**
64	* Return an optional type hint for the given array key in the result of
65	* ::toJsonArray() / input to ::newFromJsonArray.  If a class name is
66	* returned here and it matches the runtime type of the value of that
67	* array key, then type information will be omitted from the generated
68	* JSON which can save space.  The class name can be suffixed with `[]`
69	* to indicate an array or list containing objects of the given class
70	* name.
71	*
72	* @param class-string<T> $className The class we're looking for a hint for
73	* @param string $keyName The name of the array key we'd like a hint on
74	* @return class-string|string|null A class string, a class string suffixed
75	*   with `[]`, or null
76	*/
77	public function jsonClassHintFor( string $className, string $keyName ): ?string;
78	}