JSON formatter wrapper class. More...

Static Public Member Functions
static	decode ( $value, $assoc=false)
	Decodes a JSON string.

static	encode ( $value, $pretty=false, $escaping=0)
	Returns the JSON representation of a value.

static	parse ( $value, $options=0)
	Decodes a JSON string.

static	stripComments ( $json)
	Remove multiline and single line comments from an otherwise valid JSON input string.

Public Attributes
const	ALL_OK = self::UTF8_OK \| self::XMLMETA_OK
	Skip escaping as many characters as reasonably possible.

const	FORCE_ASSOC = 0x100
	If set, treat JSON objects '{...}' as associative arrays.

const	STRIP_COMMENTS = 0x400
	If set, strip comments from input before parsing as JSON.

const	TRY_FIXING = 0x200
	If set, attempt to fix invalid JSON.

const	UTF8_OK = 1
	Skip escaping most characters above U+007F for readability and compactness.

const	XMLMETA_OK = 2
	Skip escaping the characters '<', '>', and '&', which have special meanings in HTML and XML.

Detailed Description

JSON formatter wrapper class.

Definition at line 30 of file FormatJson.php.

Member Function Documentation

◆ decode()

static MediaWiki\Json\FormatJson::decode	(		$value,
			$assoc = false )

static

Decodes a JSON string.

It is recommended to use FormatJson::parse(), which returns more comprehensive result in case of an error, and has more parsing options.

In PHP versions before 7.1, decoding a JSON string containing an empty key without passing $assoc as true results in a return object with a property named "_empty_" (because true empty properties were not supported pre-PHP-7.1). Instead, consider passing $assoc as true to return an associative array.

But be aware that in all supported PHP versions, decoding an empty JSON object with $assoc = true returns an array, not an object, breaking round-trip consistency.

See https://phabricator.wikimedia.org/T206411 for more details on these quirks.

Parameters

string	$value	The JSON string being decoded
bool	$assoc	When true, returned objects will be converted into associative arrays.

Returns: mixed The value encoded in JSON in appropriate PHP type. null is returned if $value represented null, if $value could not be decoded, or if the encoded data was deeper than the recursion limit. Use FormatJson::parse() to distinguish between types of null and to get proper error code.

Definition at line 150 of file FormatJson.php.

◆ encode()

static MediaWiki\Json\FormatJson::encode	(	$value,
		$pretty = false,
		$escaping = 0 )

static

Returns the JSON representation of a value.

Note: Empty arrays are encoded as numeric arrays, not as objects, so cast any associative array that might be empty to an object before encoding it.; In pre-1.22 versions of MediaWiki, using this function for generating inline script blocks may result in an XSS vulnerability, and quite likely will in XML documents (cf. FormatJson::XMLMETA_OK). Use Xml::encodeJsVar() instead in such cases.

Parameters

mixed	$value	The value to encode. Can be any type except a resource.
string \| bool	$pretty	If a string, add non-significant whitespace to improve readability, using that string for indentation (must consist only of whitespace characters). If true, use the default indent string (four spaces).
int	$escaping	Bitfield consisting of _OK class constants

Returns: string|false String if successful; false upon failure

Definition at line 100 of file FormatJson.php.

◆ parse()

static MediaWiki\Json\FormatJson::parse	(		$value,
			$options = 0 )

static

Decodes a JSON string.

Unlike FormatJson::decode(), if $value represents null value, it will be properly decoded as valid.

Parameters

string	$value	The JSON string being decoded
int	$options	A bit field that allows FORCE_ASSOC, TRY_FIXING, STRIP_COMMENTS

Returns: Status If valid JSON, the value is available in $result->getValue()

Definition at line 164 of file FormatJson.php.

References MediaWiki\Json\FormatJson\FORCE_ASSOC, MediaWiki\Json\FormatJson\stripComments(), and wfMessage().

◆ stripComments()

static MediaWiki\Json\FormatJson::stripComments ( $json )

static

Remove multiline and single line comments from an otherwise valid JSON input string.

This can be used as a preprocessor, to allow JSON formatted configuration files to contain comments.

Parameters

string $json

Returns: string JSON with comments removed

Definition at line 234 of file FormatJson.php.

Referenced by MediaWiki\Json\FormatJson\parse().

Member Data Documentation

◆ ALL_OK

const MediaWiki\Json\FormatJson::ALL_OK = self::UTF8_OK | self::XMLMETA_OK

Skip escaping as many characters as reasonably possible.

Warning: When generating inline script blocks, use FormatJson::UTF8_OK instead.

Since: 1.22

Definition at line 59 of file FormatJson.php.

◆ FORCE_ASSOC

const MediaWiki\Json\FormatJson::FORCE_ASSOC = 0x100

If set, treat JSON objects '{...}' as associative arrays.

Without this option, JSON objects will be converted to stdClass.

Since: 1.24

Definition at line 67 of file FormatJson.php.

Referenced by MediaWiki\Json\FormatJson\parse().

◆ STRIP_COMMENTS

const MediaWiki\Json\FormatJson::STRIP_COMMENTS = 0x400

If set, strip comments from input before parsing as JSON.

Since: 1.25

Definition at line 81 of file FormatJson.php.

◆ TRY_FIXING

const MediaWiki\Json\FormatJson::TRY_FIXING = 0x200

If set, attempt to fix invalid JSON.

Since: 1.24

Definition at line 74 of file FormatJson.php.

◆ UTF8_OK

const MediaWiki\Json\FormatJson::UTF8_OK = 1

Skip escaping most characters above U+007F for readability and compactness.

This encoding option saves 3 to 8 bytes (uncompressed) for each such character; however, it could break compatibility with systems that incorrectly handle UTF-8.

Since: 1.22

Definition at line 38 of file FormatJson.php.

◆ XMLMETA_OK

const MediaWiki\Json\FormatJson::XMLMETA_OK = 2

Skip escaping the characters '<', '>', and '&', which have special meanings in HTML and XML.

Warning

Do not use this option for JSON that could end up in inline scripts.

HTML 5.2, §4.12.1.3 Restrictions for contents of script elements
XML 1.0 (5th Ed.), §2.4 Character Data and Markup

Since: 1.22

Definition at line 50 of file FormatJson.php.

The documentation for this class was generated from the following file:

includes/json/FormatJson.php

Static Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

◆ decode()

◆ encode()

◆ parse()

◆ stripComments()

Member Data Documentation

◆ ALL_OK

◆ FORCE_ASSOC

◆ STRIP_COMMENTS

◆ TRY_FIXING

◆ UTF8_OK

◆ XMLMETA_OK