Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 2
 CRAP
0.00% covered (danger)
0.00%
0 / 1
JsonCodecableTrait
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 2
 6
0.00% covered (danger)
0.00%
0 / 1
 jsonClassCodec
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 toJsonArray
n/a
0 / 0
n/a
0 / 0
 0
 newFromJsonArray
n/a
0 / 0
n/a
0 / 0
 0
 jsonClassHintFor
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
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
25use Psr\Container\ContainerInterface;
26use stdClass;
27
28/**
29 * The JsonCodecableTrait aids in the implementation of stateless codecs.
30 * The class using the trait need only define stateless ::toJsonArray() and
31 * ::newFromJsonArray() methods.
32 *
33 * The class using the trait should also implement JsonCodecable
34 * (https://wiki.php.net/rfc/traits-with-interfaces may allow the trait
35 * to do this directly in a future PHP version).
36 */
37trait JsonCodecableTrait {
38
39    /**
40     * Implements JsonCodecable by providing an implementation of
41     * ::jsonClassCodec() which does not use the provided $serviceContainer
42     * nor does it maintain any state; it just calls the ::toJsonArray()
43     * and ::newFromJsonArray() methods of this instance.
44     * @param JsonCodecInterface $codec
45     * @param ContainerInterface $serviceContainer
46     * @return JsonClassCodec
47     */
48    public static function jsonClassCodec(
49        JsonCodecInterface $codec, ContainerInterface $serviceContainer
50    ): JsonClassCodec {
51        // In advanced JIT implementations optimization of the method
52        // dispatch in this class can be performed if we keep the
53        // codecs for each class separate.  However, for simplicity
54        // (and to reduce memory usage) we'll use a singleton object
55        // shared with all classes which use this trait.
56        return JsonStaticClassCodec::getInstance();
57    }
58
59    /**
60     * Return an associative array representing the contents of this object,
61     * which can be passed to ::newFromJsonArray() to deserialize it.
62     * @return array
63     */
64    abstract public function toJsonArray(): array;
65
66    /**
67     * Return an instance of this object representing the deserialization
68     * from the array passed in $json.
69     * @param array $json
70     * @return stdClass
71     */
72    abstract public static function newFromJsonArray( array $json );
73
74    /**
75     * Return an optional type hint for the given array key in the result of
76     * ::toJsonArray() / input to ::newFromJsonArray.  If a class name is
77     * returned here and it matches the runtime type of the value of that
78     * array key, then type information will be omitted from the generated
79     * JSON which can save space.  The class name can be suffixed with `[]`
80     * to indicate an array or list containing objects of the given class
81     * name.
82     *
83     * Default implementation of ::jsonClassHintFor() provides no hints.
84     * Implementer can override.
85     *
86     * @param string $keyName
87     * @return class-string|string|null A class string, a class string suffixed
88     *   with `[]`, or null
89     */
90    public static function jsonClassHintFor( string $keyName ): ?string {
91        return null;
92    }
93}