Merge "Remove meaningless default action name"
[lhc/web/wiklou.git] / includes / json / FormatJson.php
1 <?php
2 /**
3 * Wrapper for json_encode and json_decode.
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 /**
24 * JSON formatter wrapper class
25 */
26 class FormatJson {
27 /**
28 * Skip escaping most characters above U+007F for readability and compactness.
29 * This encoding option saves 3 to 8 bytes (uncompressed) for each such character;
30 * however, it could break compatibility with systems that incorrectly handle UTF-8.
31 *
32 * @since 1.22
33 */
34 const UTF8_OK = 1;
35
36 /**
37 * Skip escaping the characters '<', '>', and '&', which have special meanings in
38 * HTML and XML.
39 *
40 * @warning Do not use this option for JSON that could end up in inline scripts.
41 * - HTML5, §4.3.1.2 Restrictions for contents of script elements
42 * - XML 1.0 (5th Ed.), §2.4 Character Data and Markup
43 *
44 * @since 1.22
45 */
46 const XMLMETA_OK = 2;
47
48 /**
49 * Skip escaping as many characters as reasonably possible.
50 *
51 * @warning When generating inline script blocks, use FormatJson::UTF8_OK instead.
52 *
53 * @since 1.22
54 */
55 const ALL_OK = 3;
56
57 /**
58 * If set, treat json objects '{...}' as associative arrays. Without this option,
59 * json objects will be converted to stdClass.
60 * The value is set to 1 to be backward compatible with 'true' that was used before.
61 *
62 * @since 1.24
63 */
64 const FORCE_ASSOC = 0x100;
65
66 /**
67 * If set, attempts to fix invalid json.
68 *
69 * @since 1.24
70 */
71 const TRY_FIXING = 0x200;
72
73 /**
74 * If set, strip comments from input before parsing as JSON.
75 *
76 * @since 1.25
77 */
78 const STRIP_COMMENTS = 0x400;
79
80 /**
81 * Regex that matches whitespace inside empty arrays and objects.
82 *
83 * This doesn't affect regular strings inside the JSON because those can't
84 * have a real line break (\n) in them, at this point they are already escaped
85 * as the string "\n" which this doesn't match.
86 *
87 * @private
88 */
89 const WS_CLEANUP_REGEX = '/(?<=[\[{])\n\s*+(?=[\]}])/';
90
91 /**
92 * Characters problematic in JavaScript.
93 *
94 * @note These are listed in ECMA-262 (5.1 Ed.), §7.3 Line Terminators along with U+000A (LF)
95 * and U+000D (CR). However, PHP already escapes LF and CR according to RFC 4627.
96 */
97 private static $badChars = array(
98 "\xe2\x80\xa8", // U+2028 LINE SEPARATOR
99 "\xe2\x80\xa9", // U+2029 PARAGRAPH SEPARATOR
100 );
101
102 /**
103 * Escape sequences for characters listed in FormatJson::$badChars.
104 */
105 private static $badCharsEscaped = array(
106 '\u2028', // U+2028 LINE SEPARATOR
107 '\u2029', // U+2029 PARAGRAPH SEPARATOR
108 );
109
110 /**
111 * Returns the JSON representation of a value.
112 *
113 * @note Empty arrays are encoded as numeric arrays, not as objects, so cast any associative
114 * array that might be empty to an object before encoding it.
115 *
116 * @note In pre-1.22 versions of MediaWiki, using this function for generating inline script
117 * blocks may result in an XSS vulnerability, and quite likely will in XML documents
118 * (cf. FormatJson::XMLMETA_OK). Use Xml::encodeJsVar() instead in such cases.
119 *
120 * @param mixed $value The value to encode. Can be any type except a resource.
121 * @param string|bool $pretty If a string, add non-significant whitespace to improve
122 * readability, using that string for indentation. If true, use the default indent
123 * string (four spaces).
124 * @param int $escaping Bitfield consisting of _OK class constants
125 * @return string|bool: String if successful; false upon failure
126 */
127 public static function encode( $value, $pretty = false, $escaping = 0 ) {
128 if ( !is_string( $pretty ) ) {
129 $pretty = $pretty ? ' ' : false;
130 }
131
132 if ( defined( 'JSON_UNESCAPED_UNICODE' ) ) {
133 return self::encode54( $value, $pretty, $escaping );
134 }
135
136 return self::encode53( $value, $pretty, $escaping );
137 }
138
139 /**
140 * Decodes a JSON string. It is recommended to use FormatJson::parse(), which returns more comprehensive
141 * result in case of an error, and has more parsing options.
142 *
143 * @param string $value The JSON string being decoded
144 * @param bool $assoc When true, returned objects will be converted into associative arrays.
145 *
146 * @return mixed The value encoded in JSON in appropriate PHP type.
147 * `null` is returned if $value represented `null`, if $value could not be decoded,
148 * or if the encoded data was deeper than the recursion limit.
149 * Use FormatJson::parse() to distinguish between types of `null` and to get proper error code.
150 */
151 public static function decode( $value, $assoc = false ) {
152 return json_decode( $value, $assoc );
153 }
154
155 /**
156 * Decodes a JSON string.
157 * Unlike FormatJson::decode(), if $value represents null value, it will be properly decoded as valid.
158 *
159 * @param string $value The JSON string being decoded
160 * @param int $options A bit field that allows FORCE_ASSOC, TRY_FIXING,
161 * STRIP_COMMENTS
162 * @return Status If valid JSON, the value is available in $result->getValue()
163 */
164 public static function parse( $value, $options = 0 ) {
165 if ( $options & self::STRIP_COMMENTS ) {
166 $value = self::stripComments( $value );
167 }
168 $assoc = ( $options & self::FORCE_ASSOC ) !== 0;
169 $result = json_decode( $value, $assoc );
170 $code = json_last_error();
171
172 if ( $code === JSON_ERROR_SYNTAX && ( $options & self::TRY_FIXING ) !== 0 ) {
173 // The most common error is the trailing comma in a list or an object.
174 // We cannot simply replace /,\s*[}\]]/ because it could be inside a string value.
175 // But we could use the fact that JSON does not allow multi-line string values,
176 // And remove trailing commas if they are et the end of a line.
177 // JSON only allows 4 control characters: [ \t\r\n]. So we must not use '\s' for matching.
178 // Regex match ,]<any non-quote chars>\n or ,\n] with optional spaces/tabs.
179 $count = 0;
180 $value =
181 preg_replace( '/,([ \t]*[}\]][^"\r\n]*([\r\n]|$)|[ \t]*[\r\n][ \t\r\n]*[}\]])/', '$1',
182 $value, - 1, $count );
183 if ( $count > 0 ) {
184 $result = json_decode( $value, $assoc );
185 if ( JSON_ERROR_NONE === json_last_error() ) {
186 // Report warning
187 $st = Status::newGood( $result );
188 $st->warning( wfMessage( 'json-warn-trailing-comma' )->numParams( $count ) );
189 return $st;
190 }
191 }
192 }
193
194 switch ( $code ) {
195 case JSON_ERROR_NONE:
196 return Status::newGood( $result );
197 default:
198 return Status::newFatal( wfMessage( 'json-error-unknown' )->numParams( $code ) );
199 case JSON_ERROR_DEPTH:
200 $msg = 'json-error-depth';
201 break;
202 case JSON_ERROR_STATE_MISMATCH:
203 $msg = 'json-error-state-mismatch';
204 break;
205 case JSON_ERROR_CTRL_CHAR:
206 $msg = 'json-error-ctrl-char';
207 break;
208 case JSON_ERROR_SYNTAX:
209 $msg = 'json-error-syntax';
210 break;
211 case JSON_ERROR_UTF8:
212 $msg = 'json-error-utf8';
213 break;
214 case JSON_ERROR_RECURSION:
215 $msg = 'json-error-recursion';
216 break;
217 case JSON_ERROR_INF_OR_NAN:
218 $msg = 'json-error-inf-or-nan';
219 break;
220 case JSON_ERROR_UNSUPPORTED_TYPE:
221 $msg = 'json-error-unsupported-type';
222 break;
223 }
224 return Status::newFatal( $msg );
225 }
226
227 /**
228 * JSON encoder wrapper for PHP >= 5.4, which supports useful encoding options.
229 *
230 * @param mixed $value
231 * @param string|bool $pretty
232 * @param int $escaping
233 * @return string|bool
234 */
235 private static function encode54( $value, $pretty, $escaping ) {
236 static $bug66021;
237 if ( $pretty !== false && $bug66021 === null ) {
238 $bug66021 = json_encode( array(), JSON_PRETTY_PRINT ) !== '[]';
239 }
240
241 // PHP escapes '/' to prevent breaking out of inline script blocks using '</script>',
242 // which is hardly useful when '<' and '>' are escaped (and inadequate), and such
243 // escaping negatively impacts the human readability of URLs and similar strings.
244 $options = JSON_UNESCAPED_SLASHES;
245 $options |= $pretty !== false ? JSON_PRETTY_PRINT : 0;
246 $options |= ( $escaping & self::UTF8_OK ) ? JSON_UNESCAPED_UNICODE : 0;
247 $options |= ( $escaping & self::XMLMETA_OK ) ? 0 : ( JSON_HEX_TAG | JSON_HEX_AMP );
248 $json = json_encode( $value, $options );
249 if ( $json === false ) {
250 return false;
251 }
252
253 if ( $pretty !== false ) {
254 // Workaround for <https://bugs.php.net/bug.php?id=66021>
255 if ( $bug66021 ) {
256 $json = preg_replace( self::WS_CLEANUP_REGEX, '', $json );
257 }
258 if ( $pretty !== ' ' ) {
259 // Change the four-space indent to a tab indent
260 $json = str_replace( "\n ", "\n\t", $json );
261 while ( strpos( $json, "\t " ) !== false ) {
262 $json = str_replace( "\t ", "\t\t", $json );
263 }
264
265 if ( $pretty !== "\t" ) {
266 // Change the tab indent to the provided indent
267 $json = str_replace( "\t", $pretty, $json );
268 }
269 }
270 }
271 if ( $escaping & self::UTF8_OK ) {
272 $json = str_replace( self::$badChars, self::$badCharsEscaped, $json );
273 }
274
275 return $json;
276 }
277
278 /**
279 * JSON encoder wrapper for PHP 5.3, which lacks native support for some encoding options.
280 * Therefore, the missing options are implemented here purely in PHP code.
281 *
282 * @param mixed $value
283 * @param string|bool $pretty
284 * @param int $escaping
285 * @return string|bool
286 */
287 private static function encode53( $value, $pretty, $escaping ) {
288 $options = ( $escaping & self::XMLMETA_OK ) ? 0 : ( JSON_HEX_TAG | JSON_HEX_AMP );
289 $json = json_encode( $value, $options );
290 if ( $json === false ) {
291 return false;
292 }
293
294 // Emulate JSON_UNESCAPED_SLASHES. Because the JSON contains no unescaped slashes
295 // (only escaped slashes), a simple string replacement works fine.
296 $json = str_replace( '\/', '/', $json );
297
298 if ( $escaping & self::UTF8_OK ) {
299 // JSON hex escape sequences follow the format \uDDDD, where DDDD is four hex digits
300 // indicating the equivalent UTF-16 code unit's value. To most efficiently unescape
301 // them, we exploit the JSON extension's built-in decoder.
302 // * We escape the input a second time, so any such sequence becomes \\uDDDD.
303 // * To avoid interpreting escape sequences that were in the original input,
304 // each double-escaped backslash (\\\\) is replaced with \\\u005c.
305 // * We strip one of the backslashes from each of the escape sequences to unescape.
306 // * Then the JSON decoder can perform the actual unescaping.
307 $json = str_replace( "\\\\\\\\", "\\\\\\u005c", addcslashes( $json, '\"' ) );
308 $json = json_decode( preg_replace( "/\\\\\\\\u(?!00[0-7])/", "\\\\u", "\"$json\"" ) );
309 $json = str_replace( self::$badChars, self::$badCharsEscaped, $json );
310 }
311
312 if ( $pretty !== false ) {
313 return self::prettyPrint( $json, $pretty );
314 }
315
316 return $json;
317 }
318
319 /**
320 * Adds non-significant whitespace to an existing JSON representation of an object.
321 * Only needed for PHP < 5.4, which lacks the JSON_PRETTY_PRINT option.
322 *
323 * @param string $json
324 * @param string $indentString
325 * @return string
326 */
327 private static function prettyPrint( $json, $indentString ) {
328 $buf = '';
329 $indent = 0;
330 $json = strtr( $json, array( '\\\\' => '\\\\', '\"' => "\x01" ) );
331 for ( $i = 0, $n = strlen( $json ); $i < $n; $i += $skip ) {
332 $skip = 1;
333 switch ( $json[$i] ) {
334 case ':':
335 $buf .= ': ';
336 break;
337 case '[':
338 case '{':
339 ++$indent;
340 // falls through
341 case ',':
342 $buf .= $json[$i] . "\n" . str_repeat( $indentString, $indent );
343 break;
344 case ']':
345 case '}':
346 $buf .= "\n" . str_repeat( $indentString, --$indent ) . $json[$i];
347 break;
348 case '"':
349 $skip = strcspn( $json, '"', $i + 1 ) + 2;
350 $buf .= substr( $json, $i, $skip );
351 break;
352 default:
353 $skip = strcspn( $json, ',]}"', $i + 1 ) + 1;
354 $buf .= substr( $json, $i, $skip );
355 }
356 }
357 $buf = preg_replace( self::WS_CLEANUP_REGEX, '', $buf );
358
359 return str_replace( "\x01", '\"', $buf );
360 }
361
362 /**
363 * Remove multiline and single line comments from an otherwise valid JSON
364 * input string. This can be used as a preprocessor for to allow JSON
365 * formatted configuration files to contain comments.
366 *
367 * @param string $json
368 * @return string JSON with comments removed
369 */
370 public static function stripComments( $json ) {
371 // Ensure we have a string
372 $str = (string) $json;
373 $buffer = '';
374 $maxLen = strlen( $str );
375 $mark = 0;
376
377 $inString = false;
378 $inComment = false;
379 $multiline = false;
380
381 for ($idx = 0; $idx < $maxLen; $idx++) {
382 switch ( $str[$idx] ) {
383 case '"':
384 $lookBehind = ( $idx - 1 >= 0 ) ? $str[$idx - 1] : '';
385 if ( !$inComment && $lookBehind !== '\\' ) {
386 // Either started or ended a string
387 $inString = !$inString;
388 }
389 break;
390
391 case '/':
392 $lookAhead = ( $idx + 1 < $maxLen ) ? $str[$idx + 1] : '';
393 $lookBehind = ( $idx - 1 >= 0 ) ? $str[$idx - 1] : '';
394 if ( $inString ) {
395 continue;
396
397 } elseif ( !$inComment &&
398 ( $lookAhead === '/' || $lookAhead === '*' )
399 ) {
400 // Transition into a comment
401 // Add characters seen to buffer
402 $buffer .= substr( $str, $mark, $idx - $mark );
403 // Consume the look ahead character
404 $idx++;
405 // Track state
406 $inComment = true;
407 $multiline = $lookAhead === '*';
408
409 } elseif ( $multiline && $lookBehind === '*' ) {
410 // Found the end of the current comment
411 $mark = $idx + 1;
412 $inComment = false;
413 $multiline = false;
414 }
415 break;
416
417 case "\n":
418 if ( $inComment && !$multiline ) {
419 // Found the end of the current comment
420 $mark = $idx + 1;
421 $inComment = false;
422 }
423 break;
424 }
425 }
426 if ( $inComment ) {
427 // Comment ends with input
428 // Technically we should check to ensure that we aren't in
429 // a multiline comment that hasn't been properly ended, but this
430 // is a strip filter, not a validating parser.
431 $mark = $maxLen;
432 }
433 // Add final chunk to buffer before returning
434 return $buffer . substr( $str, $mark, $maxLen - $mark );
435 }
436 }