Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00% covered (success)
100.00%
23 / 23
100.00% covered (success)
100.00%
7 / 7
 CRAP
100.00% covered (success)
100.00%
1 / 1
DataMessageValue
100.00% covered (success)
100.00%
23 / 23
100.00% covered (success)
100.00%
7 / 7
 10
100.00% covered (success)
100.00%
1 / 1
 __construct
100.00% covered (success)
100.00%
3 / 3
100.00% covered (success)
100.00%
1 / 1
 1
 new
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 getCode
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 getData
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 dump
100.00% covered (success)
100.00%
12 / 12
100.00% covered (success)
100.00%
1 / 1
 4
 toJsonArray
100.00% covered (success)
100.00%
4 / 4
100.00% covered (success)
100.00%
1 / 1
 1
 newFromJsonArray
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
1<?php
2/**
3 * This program is free software; you can redistribute it and/or modify
4 * it under the terms of the GNU General Public License as published by
5 * the Free Software Foundation; either version 2 of the License, or
6 * (at your option) any later version.
7 *
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU General Public License for more details.
12 *
13 * You should have received a copy of the GNU General Public License along
14 * with this program; if not, write to the Free Software Foundation, Inc.,
15 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16 * http://www.gnu.org/copyleft/gpl.html
17 *
18 * @file
19 */
20
21namespace Wikimedia\Message;
22
23use Wikimedia\JsonCodec\JsonCodecableTrait;
24
25/**
26 * Value object representing a message for i18n with alternative
27 * machine-readable data.
28 *
29 * This augments a MessageValue with an additional machine-readable code and
30 * structured data. The intended use is to facilitate error reporting in APIs.
31 *
32 * For example, a MessageValue reporting an "integer out of range" error might
33 * use one of three message keys, depending on whether there is a minimum, a
34 * maximum, or both. But an API would likely want to use one code for all three
35 * cases, and would likely want the endpoints represented along the lines of
36 * `[ 'min' => 1, 'max' => 10 ]` rather than
37 * `[ 0 => new ScalarParam( ParamType::TEXT, 1 ), 1 => new ScalarParam( ParamType::TEXT, 10 ) ]`.
38 *
39 * DataMessageValues are pure value objects and are newable and (de)serializable.
40 *
41 * @newable
42 */
43class DataMessageValue extends MessageValue {
44    use JsonCodecableTrait;
45
46    private string $code;
47    private ?array $data;
48
49    /**
50     * @stable to call
51     *
52     * @param string $key
53     * @param (MessageParam|MessageValue|string|int|float)[] $params
54     * @param string|null $code String representing the concept behind
55     *  this message.
56     * @param array|null $data Structured data representing the concept
57     *  behind this message.
58     */
59    public function __construct( string $key, array $params = [], ?string $code = null, ?array $data = null ) {
60        parent::__construct( $key, $params );
61
62        $this->code = $code ?? $key;
63        $this->data = $data;
64    }
65
66    /**
67     * Static constructor for easier chaining of `->params()` methods
68     *
69     * @param string $key
70     * @param (MessageParam|MessageValue|string|int|float)[] $params
71     * @param string|null $code
72     * @param array|null $data
73     *
74     * @return DataMessageValue
75     */
76    public static function new(
77        string $key,
78        array $params = [],
79        ?string $code = null,
80        ?array $data = null
81    ): DataMessageValue {
82        return new DataMessageValue( $key, $params, $code, $data );
83    }
84
85    /**
86     * Get the message code
87     * @return string
88     */
89    public function getCode(): string {
90        return $this->code;
91    }
92
93    /**
94     * Get the message's structured data
95     * @return array|null
96     */
97    public function getData(): ?array {
98        return $this->data;
99    }
100
101    public function dump(): string {
102        $contents = '';
103        if ( $this->getParams() ) {
104            $contents = '<params>';
105            foreach ( $this->getParams() as $param ) {
106                $contents .= $param->dump();
107            }
108            $contents .= '</params>';
109        }
110
111        if ( $this->data !== null ) {
112            $contents .= '<data>' . htmlspecialchars( json_encode( $this->data ), ENT_NOQUOTES ) . '</data>';
113        }
114
115        return '<datamessage key="' . htmlspecialchars( $this->getKey() ) . '"'
116            . ' code="' . htmlspecialchars( $this->code ) . '">'
117            . $contents
118            . '</datamessage>';
119    }
120
121    public function toJsonArray(): array {
122        // WARNING: When changing how this class is serialized, follow the instructions
123        // at <https://www.mediawiki.org/wiki/Manual:Parser_cache/Serialization_compatibility>!
124        return parent::toJsonArray() + [
125                'code' => $this->code,
126                'data' => $this->data,
127            ];
128    }
129
130    public static function newFromJsonArray( array $json ): DataMessageValue {
131        // WARNING: When changing how this class is serialized, follow the instructions
132        // at <https://www.mediawiki.org/wiki/Manual:Parser_cache/Serialization_compatibility>!
133        return new self( $json['key'], $json['params'], $json['code'], $json['data'] );
134    }
135}