MediaWiki  1.23.2
FormatJson Class Reference

JSON formatter wrapper class. More...

Static Public Member Functions

static decode ( $value, $assoc=false)
 Decodes a JSON string. More...
 
static encode ( $value, $pretty=false, $escaping=0)
 Returns the JSON representation of a value. More...
 

Public Attributes

const ALL_OK = 3
 Skip escaping as many characters as reasonably possible. More...
 
const UTF8_OK = 1
 Skip escaping most characters above U+007F for readability and compactness. More...
 
const WS_CLEANUP_REGEX = '/(?<=[\[{])\n\s*+(?=[\]}])/'
 Regex that matches whitespace inside empty arrays and objects. More...
 
const XMLMETA_OK = 2
 Skip escaping the characters '<', '>', and '&', which have special meanings in HTML and XML. More...
 

Static Private Member Functions

static encode53 ( $value, $pretty, $escaping)
 JSON encoder wrapper for PHP 5.3, which lacks native support for some encoding options. More...
 
static encode54 ( $value, $pretty, $escaping)
 JSON encoder wrapper for PHP >= 5.4, which supports useful encoding options. More...
 
static prettyPrint ( $json, $indentString)
 Adds non-significant whitespace to an existing JSON representation of an object. More...
 

Static Private Attributes

static $badChars
 Characters problematic in JavaScript. More...
 
static $badCharsEscaped
 Escape sequences for characters listed in FormatJson::$badChars. More...
 

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.

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 the JSON cannot be decoded or if the encoded data is deeper than the recursion limit.

Definition at line 126 of file FormatJson.php.

References $value.

Referenced by GenerateJsonI18n\doShim(), ForeignAPIRepo\fetchImageQuery(), ResourceLoaderModule\getFileDependencies(), MessageBlobStore\getFromDB(), ForeignAPIRepo\getInfo(), MediaWikiSite\normalizePageName(), SwiftFileBackend\objectListing(), ResourceLoader\preloadModuleInfo(), LocalisationCache\readJSONFile(), MessageBlobStore\reencodeBlob(), FormatJsonTest\testDecodeReturnType(), and MessageBlobStore\updateModule().

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

Definition at line 104 of file FormatJson.php.

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

Referenced by FileBackendMultiWrite\doOperationsInternal(), GenerateJsonI18n\execute(), ApiFormatJson\execute(), GetConfiguration\execute(), JSONRCFeedFormatter\formatArray(), MessageBlobStore\generateMessageBlob(), ResourceLoaderFileModule\getStyles(), MWExceptionHandler\jsonSerializeException(), FileOp\logFailure(), SwiftFileBackend\onError(), MessageBlobStore\reencodeBlob(), FormatJsonTest\testEncodeAllOk(), FormatJsonTest\testEncodeDefault(), FormatJsonTest\testEncodePhpBug46944(), FormatJsonTest\testEncoderPrettyPrinting(), FormatJsonTest\testEncodeUtf8(), FormatJsonTest\testEncodeXmlMeta(), and GenerateJqueryMsgData\writeJavascriptFile().

◆ encode53()

static FormatJson::encode53 (   $value,
  $pretty,
  $escaping 
)
staticprivate

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

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

Referenced by encode().

◆ encode54()

static FormatJson::encode54 (   $value,
  $pretty,
  $escaping 
)
staticprivate

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

References $options, $value, UTF8_OK, and XMLMETA_OK.

Referenced by encode().

◆ prettyPrint()

static FormatJson::prettyPrint (   $json,
  $indentString 
)
staticprivate

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

References $n, and array().

Referenced by encode53().

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

◆ $badCharsEscaped

FormatJson::$badCharsEscaped
staticprivate
Initial value:
'\u2028',
'\u2029',
)

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

Definition at line 82 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.

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

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

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

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

Access:\n private

Definition at line 66 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.

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


The documentation for this class was generated from the following file:
array
the array() calling protocol came about after MediaWiki 1.4rc1.
List of Api Query prop modules.