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.
Public Attributes
const	ALL_OK = 3
	Skip escaping as many characters as reasonably possible.
const	FORCE_ASSOC = 0x100
	If set, treat json objects '{...}' as associative arrays.
const	TRY_FIXING = 0x200
	If set, attempts to fix invalid json.
const	UTF8_OK = 1
	Skip escaping most characters above U+007F for readability and compactness.
const	WS_CLEANUP_REGEX = '/(?<=[\[{])\n\s*+(?=[\]}])/'
	Regex that matches whitespace inside empty arrays and objects.
const	XMLMETA_OK = 2
	Skip escaping the characters '<', '>', and '&', which have special meanings in HTML and XML.
Static Private Member Functions
static	encode53 ($value, $pretty, $escaping)
	JSON encoder wrapper for PHP 5.3, which lacks native support for some encoding options.
static	encode54 ($value, $pretty, $escaping)
	JSON encoder wrapper for PHP >= 5.4, which supports useful encoding options.
static	prettyPrint ($json, $indentString)
	Adds non-significant whitespace to an existing JSON representation of an object.
Static Private Attributes
static	$badChars
	Characters problematic in JavaScript.
static	$badCharsEscaped
	Escape sequences for characters listed in FormatJson::$badChars.

Detailed Description

JSON formatter wrapper class.

Definition at line 26 of file FormatJson.php.

Member Function Documentation

static 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.

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 144 of file FormatJson.php.

References $value.

Referenced by GitInfo\__construct(), JsonContent\beautifyJSON(), GenerateJsonI18n\doShim(), MessageBlobStore\getFromDB(), JsonContent\getJsonData(), MediaWikiSite\normalizePageName(), MessageBlobStore\reencodeBlob(), FormatJsonTest\testDecodeReturnType(), HtmlAutoCompleteSelectFieldTest\testGetAttributes(), and MessageBlobStore\updateModule().

static 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. If true, use the default indent string (four spaces).
int	$escaping	Bitfield consisting of _OK class constants

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

Definition at line 120 of file FormatJson.php.

References $value, encode53(), and encode54().

Referenced by JsonContent\beautifyJSON(), SpecialRunJobs\execute(), ListVariants\execute(), RunJobs\execute(), ApiFormatJson\execute(), GetConfiguration\execute(), JSONRCFeedFormatter\formatArray(), MessageBlobStore\generateMessageBlob(), HTMLAutoCompleteSelectField\getAttributes(), MWExceptionHandler\jsonSerializeException(), JsonContent\objectRow(), GitInfo\precomputeValues(), JsonContentTest\provideValidConstruction(), MessageBlobStore\reencodeBlob(), JsonContentTest\testBeautifyUsesFormatJson(), FormatJsonTest\testEncodeAllOk(), FormatJsonTest\testEncodeDefault(), FormatJsonTest\testEncodePhpBug46944(), FormatJsonTest\testEncoderPrettyPrinting(), FormatJsonTest\testEncodeUtf8(), FormatJsonTest\testEncodeXmlMeta(), JsonContentTest\testFillParserOutput(), FormatJsonTest\testParse(), FormatJsonTest\testParseTryFixing(), JsonContentTest\testPreSaveTransform(), GenerateJsonI18n\transformI18nFile(), and GenerateJqueryMsgData\writeJavascriptFile().

static FormatJson::encode53	(	$	value,
		$	pretty,
		$	escaping
	)		`[static, private]`

JSON encoder wrapper for PHP 5.3, which lacks native support for some encoding options.

Therefore, the missing options are implemented here purely in PHP code.

Parameters:

mixed	$value
string \| bool	$pretty
int	$escaping

Returns:: string|bool

Definition at line 276 of file FormatJson.php.

References $options, $value, prettyPrint(), and XMLMETA_OK.

Referenced by encode().

static FormatJson::encode54	(	$	value,
		$	pretty,
		$	escaping
	)		`[static, private]`

JSON encoder wrapper for PHP >= 5.4, which supports useful encoding options.

Parameters:

mixed	$value
string \| bool	$pretty
int	$escaping

Returns:: string|bool

Definition at line 224 of file FormatJson.php.

References $options, $value, array(), UTF8_OK, and XMLMETA_OK.

Referenced by encode().

static 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

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

Definition at line 156 of file FormatJson.php.

References $count, $options, $result, $value, FORCE_ASSOC, Status\newFatal(), Status\newGood(), and wfMessage().

Referenced by FormatJsonTest\testParse(), FormatJsonTest\testParseErrors(), and FormatJsonTest\testParseTryFixing().

static FormatJson::prettyPrint	(	$	json,
		$	indentString
	)		`[static, private]`

Adds non-significant whitespace to an existing JSON representation of an object.

Only needed for PHP < 5.4, which lacks the JSON_PRETTY_PRINT option.

Parameters:

string	$json
string	$indentString

Returns:: string

Definition at line 316 of file FormatJson.php.

References $n, and array().

Referenced by encode53().

Member Data Documentation

FormatJson::$badChars [static, private]

Initial value:

 array(
        "\xe2\x80\xa8", 
        "\xe2\x80\xa9", 
    )

Characters problematic in JavaScript.

Note:: These are listed in ECMA-262 (5.1 Ed.), §7.3 Line Terminators along with U+000A (LF) and U+000D (CR). However, PHP already escapes LF and CR according to RFC 4627.

Definition at line 90 of file FormatJson.php.

FormatJson::$badCharsEscaped [static, private]

Initial value:

 array(
        '\u2028', 
        '\u2029', 
    )

Escape sequences for characters listed in FormatJson::$badChars.

Definition at line 98 of file FormatJson.php.

const FormatJson::ALL_OK = 3

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 55 of file FormatJson.php.

Referenced by ApiFormatJson\execute(), MWExceptionHandler\logException(), FormatJsonTest\testEncodeAllOk(), FormatJsonTest\testParse(), FormatJsonTest\testParseTryFixing(), and GenerateJsonI18n\transformI18nFile().

const FormatJson::FORCE_ASSOC = 0x100

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

Without this option, json objects will be converted to stdClass. The value is set to 1 to be backward compatible with 'true' that was used before.

Since:: 1.24

Definition at line 64 of file FormatJson.php.

Referenced by parse(), and FormatJsonTest\testParse().

const FormatJson::TRY_FIXING = 0x200

If set, attempts to fix invalid json.

Since:: 1.24

Definition at line 71 of file FormatJson.php.

Referenced by FormatJsonTest\testParseTryFixing().

const 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 34 of file FormatJson.php.

Referenced by encode54(), and FormatJsonTest\testEncodeUtf8().

const FormatJson::WS_CLEANUP_REGEX = '/(?<=[\[{])\n\s*+(?=[\]}])/'

Regex that matches whitespace inside empty arrays and objects.

This doesn't affect regular strings inside the JSON because those can't have a real line break (
) in them, at this point they are already escaped as the string "\n" which this doesn't match.

Access:: private

Definition at line 82 of file FormatJson.php.

const 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.

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

Since:: 1.22

Definition at line 46 of file FormatJson.php.

Referenced by encode53(), encode54(), ApiFormatJson\execute(), and FormatJsonTest\testEncodeXmlMeta().

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

includes/json/FormatJson.php

Static Public Member Functions

Public Attributes

Static Private Member Functions

Static Private Attributes

Detailed Description

Member Function Documentation

Member Data Documentation