MediaWiki REL1_28
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$valueThe JSON string being decoded
bool$assocWhen 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$valueThe value to encode. Can be any type except a resource.
string | bool$prettyIf a string, add non-significant whitespace to improve readability, using that string for indentation. If true, use the default indent string (four spaces).
int$escapingBitfield 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$valueThe JSON string being decoded
int$optionsA 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: