Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
n/a
0 / 0
n/a
0 / 0
CRAP
n/a
0 / 0
1<?php
2declare( 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
23namespace 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 */
34interface 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|Hint|null A class string, Hint or null.
75     *   For backward compatibility, a class string suffixed with `[]` can
76     *   also be returned, but that is deprecated.
77     */
78    public function jsonClassHintFor( string $className, string $keyName );
79}