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	* Interface used to serialize/unserialize things to/from JSON.  This
27	* interface only contains the two fundamental methods from JsonCodec,
28	* and is intended to be used (when necessary) by JsonClassCodec
29	* implementations which need to manually serialize/deserialize components
30	* of their representation.  For example:
31	* ```
32	* class FooCodec extends JsonClassCodec {
33	*   private JsonCodecInterface $codec;
34	*   ...
35	*   public function newFromJsonArray( string $className, array $json ): Foo {
36	*       $tag = $json['tag'];
37	*       // Based on the $tag we can infer the appropriate type for $value
38	*       // and don't need to explicitly include it in $json:
39	*       switch ($tag) {
40	*       case 'bar':
41	*         $value = $this->codec->newFromJsonArray( $json['value'], Bar::class );
42	*         break;
43	*       case 'bat':
44	*         $value = $this->codec->newFromJsonArray( $json['value'], Bat::class );
45	*         break;
46	*       ...
47	*       }
48	*       return new Foo($tag, $value);
49	*   }
50	* }
51	* ```
52	* Generally speaking, explicitly invoking the codec to deserialize properties
53	* of $json is not required; the deserialization is handled automatically
54	* using the type annotations embedded in the JSON.  This style of explicit
55	* serialization/deserialization is only necessary when implicit types are
56	* used, and they are used in a manner which can't be represented by
57	* JsonClassCodec::jsonClassHintFor().  In addition to tagged unions like the
58	* above example, implicit types for objects embedded within array components
59	* might be another use case.
60	*/
61	interface JsonCodecInterface {
62	/**
63	* Recursively converts a given object to an associative array
64	* which can be json-encoded.  (When embeddeding an object into
65	* another context it is sometimes useful to have the array
66	* representation rather than the string JSON form of the array;
67	* this can also be useful if you want to pretty-print the result,
68	* etc.)  While converting $value the JsonCodec delegates to the
69	* appropriate JsonClassCodecs of any classes which implement
70	* JsonCodecable.
71	*
72	* If a $classHint is provided and matches the type of the value,
73	* then type information will not be included in the generated JSON;
74	* otherwise an appropriate class name will be added to the JSON to
75	* guide deserialization.
76	*
77	* @param mixed|null $value
78	* @param ?class-string $classHint An optional hint to
79	*   the type of the encoded object.  If this is provided and matches
80	*   the type of $value, then explicit type information will be omitted
81	*   from the generated JSON, which saves some space.
82	* @return mixed|null
83	*/
84	public function toJsonArray( $value, ?string $classHint = null );
85
86	/**
87	* Recursively converts an associative array (or scalar) to an
88	* object value (or scalar).  While converting this value JsonCodec
89	* delegates to the appropriate JsonClassCodecs of any classes which
90	* implement JsonCodecable.
91	*
92	* For objects encoded using implicit class information, a "class hint"
93	* can be provided to guide deserialization; this is unnecessary for
94	* objects serialized with explicit classes.
95	*
96	* @param mixed|null $json
97	* @param ?class-string $classHint An optional hint to
98	*   the type of the encoded object.  In the absence of explicit
99	*   type information in the JSON, this will be used as the type of
100	*   the created object.
101	* @return mixed|null
102	*/
103	public function newFromJsonArray( $json, ?string $classHint = null );
104	}