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