FormatJson Class Reference

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 = 3
	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, 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 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

decode()

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

References $value.

Referenced by MediaWiki\Site\MediaWikiPageNameNormalizer\normalizePageName().

encode()

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|false String if successful; false upon failure

Definition at line 127 of file FormatJson.php.

References $options, and $value.

parse()

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, STRIP_COMMENTS

Returns

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

Definition at line 201 of file FormatJson.php.

References $code, $count, $options, $value, and wfMessage().

stripComments()

static FormatJson::stripComments (   $json )

static

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

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

Parameters

string

$json

Returns

string JSON with comments removed

Definition at line 272 of file FormatJson.php.

References $buffer, and string.

Member Data Documentation

$badChars

FormatJson::$badChars

staticprivate

Initial value:

= [
        "\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 97 of file FormatJson.php.

$badCharsEscaped

FormatJson::$badCharsEscaped

staticprivate

Initial value:

= [
        '\u2028', 
        '\u2029', 
    ]

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

Definition at line 105 of file FormatJson.php.

ALL_OK

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.

FORCE_ASSOC

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.

STRIP_COMMENTS

const FormatJson::STRIP_COMMENTS = 0x400

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

Since

1.25

Definition at line 78 of file FormatJson.php.

TRY_FIXING

const FormatJson::TRY_FIXING = 0x200

If set, attempts to fix invalid json.

Since

1.24

Definition at line 71 of file FormatJson.php.

UTF8_OK

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.

WS_CLEANUP_REGEX

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 (\n) in them, at this point they are already escaped as the string "\\n" which this doesn't match.

Access:\n private

Definition at line 89 of file FormatJson.php.

XMLMETA_OK

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.

---

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

• includes/json/FormatJson.php