Class yii\helpers\BaseJson
Inheritance | yii\helpers\BaseJson |
---|---|
Subclasses | yii\helpers\Json |
Available since version | 2.0 |
Source Code | https://github.com/yiisoft/yii2/blob/master/framework/helpers/BaseJson.php |
BaseJson provides concrete implementation for yii\helpers\Json.
Do not use BaseJson. Use yii\helpers\Json instead.
Public Properties
Property | Type | Description | Defined By |
---|---|---|---|
$jsonErrorMessages | array | List of JSON Error messages assigned to constant names for better handling of PHP <= 5.5. | yii\helpers\BaseJson |
$keepObjectType | boolean | Avoids objects with zero-indexed keys to be encoded as array Json::encode((object)['test']) will be encoded as an object not as an array. | yii\helpers\BaseJson |
$prettyPrint | boolean|null | Enables human readable output a.k.a. | yii\helpers\BaseJson |
Public Methods
Method | Description | Defined By |
---|---|---|
decode() | Decodes the given JSON string into a PHP data structure. | yii\helpers\BaseJson |
encode() | Encodes the given value into a JSON string. | yii\helpers\BaseJson |
errorSummary() | Generates a summary of the validation errors. | yii\helpers\BaseJson |
htmlEncode() | Encodes the given value into a JSON string HTML-escaping entities so it is safe to be embedded in HTML code. | yii\helpers\BaseJson |
Protected Methods
Method | Description | Defined By |
---|---|---|
handleJsonError() | Handles encode() and decode() errors by throwing exceptions with the respective error message. | yii\helpers\BaseJson |
processData() | Pre-processes the data before sending it to json_encode() . | yii\helpers\BaseJson |
Property Details
List of JSON Error messages assigned to constant names for better handling of PHP <= 5.5.
'JSON_ERROR_SYNTAX' => 'Syntax error',
'JSON_ERROR_UNSUPPORTED_TYPE' => 'Type is not supported',
'JSON_ERROR_DEPTH' => 'The maximum stack depth has been exceeded',
'JSON_ERROR_STATE_MISMATCH' => 'Invalid or malformed JSON',
'JSON_ERROR_CTRL_CHAR' => 'Control character error, possibly incorrectly encoded',
'JSON_ERROR_UTF8' => 'Malformed UTF-8 characters, possibly incorrectly encoded',
]
Avoids objects with zero-indexed keys to be encoded as array Json::encode((object)['test'])
will be encoded as an object not as an array. This matches the behaviour of json_encode()
. Defaults to false to avoid any backwards compatibility issues. Enable for single purpose: Json::$keepObjectType = true;
See also yii\web\JsonResponseFormatter documentation to enable for all JSON responses.
Enables human readable output a.k.a. Pretty Print. This can useful for debugging during development but is not recommended in a production environment! In case prettyPrint
is null
(default) the options
passed to encode
functions will not be changed.
Method Details
Decodes the given JSON string into a PHP data structure.
public static mixed decode ( $json, $asArray = true ) | ||
$json | string | The JSON string to be decoded |
$asArray | boolean | Whether to return objects in terms of associative arrays. |
return | mixed | The PHP data |
---|---|---|
throws | yii\base\InvalidArgumentException | if there is any decoding error |
public static function decode($json, $asArray = true) { if (is_array($json)) { throw new InvalidArgumentException('Invalid JSON data.'); } elseif ($json === null || $json === '') { return null; } $decode = json_decode((string) $json, $asArray); static::handleJsonError(json_last_error()); return $decode; }
Encodes the given value into a JSON string.
The method enhances json_encode()
by supporting JavaScript expressions. In particular, the method will not encode a JavaScript expression that is represented in terms of a yii\web\JsExpression object.
Note that data encoded as JSON must be UTF-8 encoded according to the JSON specification. You must ensure strings passed to this method have proper encoding before passing them.
public static string encode ( $value, $options = 320 ) | ||
$value | mixed | The data to be encoded. |
$options | integer | The encoding options. For more details please refer to https://www.php.net/manual/en/function.json-encode.php. Default is |
return | string | The encoding result. |
---|---|---|
throws | yii\base\InvalidArgumentException | if there is any encoding error. |
public static function encode($value, $options = 320) { $expressions = []; $value = static::processData($value, $expressions, uniqid('', true)); set_error_handler(function () { static::handleJsonError(JSON_ERROR_SYNTAX); }, E_WARNING); if (static::$prettyPrint === true) { $options |= JSON_PRETTY_PRINT; } elseif (static::$prettyPrint === false) { $options &= ~JSON_PRETTY_PRINT; } $json = json_encode($value, $options); restore_error_handler(); static::handleJsonError(json_last_error()); return $expressions === [] ? $json : strtr($json, $expressions); }
Generates a summary of the validation errors.
public static string errorSummary ( $models, $options = [] ) | ||
$models | yii\base\Model|yii\base\Model[] | The model(s) whose validation errors are to be displayed. |
$options | array | The tag options in terms of name-value pairs. The following options are specially handled:
|
return | string | The generated error summary |
---|
public static function errorSummary($models, $options = []) { $showAllErrors = ArrayHelper::remove($options, 'showAllErrors', false); $lines = self::collectErrors($models, $showAllErrors); return static::encode($lines); }
protected static void handleJsonError ( $lastError ) | ||
$lastError | integer | Error code from json_last_error(). |
throws | yii\base\InvalidArgumentException | if there is any encoding/decoding error. |
---|
protected static function handleJsonError($lastError) { if ($lastError === JSON_ERROR_NONE) { return; } if (PHP_VERSION_ID >= 50500) { throw new InvalidArgumentException(json_last_error_msg(), $lastError); } foreach (static::$jsonErrorMessages as $const => $message) { if (defined($const) && constant($const) === $lastError) { throw new InvalidArgumentException($message, $lastError); } } throw new InvalidArgumentException('Unknown JSON encoding/decoding error.'); }
Encodes the given value into a JSON string HTML-escaping entities so it is safe to be embedded in HTML code.
The method enhances json_encode()
by supporting JavaScript expressions. In particular, the method will not encode a JavaScript expression that is represented in terms of a yii\web\JsExpression object.
Note that data encoded as JSON must be UTF-8 encoded according to the JSON specification. You must ensure strings passed to this method have proper encoding before passing them.
public static string htmlEncode ( $value ) | ||
$value | mixed | The data to be encoded |
return | string | The encoding result |
---|---|---|
throws | yii\base\InvalidArgumentException | if there is any encoding error |
public static function htmlEncode($value) { return static::encode($value, JSON_UNESCAPED_UNICODE | JSON_HEX_QUOT | JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS); }
Pre-processes the data before sending it to json_encode()
.
protected static mixed processData ( $data, &$expressions, $expPrefix ) | ||
$data | mixed | The data to be processed |
$expressions | array | Collection of JavaScript expressions |
$expPrefix | string | A prefix internally used to handle JS expressions |
return | mixed | The processed data |
---|
protected static function processData($data, &$expressions, $expPrefix) { $revertToObject = false; if (is_object($data)) { if ($data instanceof JsExpression) { $token = "!{[$expPrefix=" . count($expressions) . ']}!'; $expressions['"' . $token . '"'] = $data->expression; return $token; } if ($data instanceof \JsonSerializable) { return static::processData($data->jsonSerialize(), $expressions, $expPrefix); } if ($data instanceof \DateTimeInterface) { return static::processData((array)$data, $expressions, $expPrefix); } if ($data instanceof Arrayable) { $data = $data->toArray(); } elseif ($data instanceof \Generator) { $_data = []; foreach ($data as $name => $value) { $_data[$name] = static::processData($value, $expressions, $expPrefix); } $data = $_data; } elseif ($data instanceof \SimpleXMLElement) { $data = (array) $data; // Avoid empty elements to be returned as array. // Not breaking BC because empty array was always cast to stdClass before. $revertToObject = true; } else { /* * $data type is changed to array here and its elements will be processed further * We must cast $data back to object later to keep intended dictionary type in JSON. * Revert is only done when keepObjectType flag is provided to avoid breaking BC */ $revertToObject = static::$keepObjectType; $result = []; foreach ($data as $name => $value) { $result[$name] = $value; } $data = $result; // Avoid empty objects to be returned as array (would break BC without keepObjectType flag) if ($data === []) { $revertToObject = true; } } } if (is_array($data)) { foreach ($data as $key => $value) { if (is_array($value) || is_object($value)) { $data[$key] = static::processData($value, $expressions, $expPrefix); } } } return $revertToObject ? (object) $data : $data; }
Signup or Login in order to comment.