0 追蹤者

Class yii\helpers\BaseJson

繼承yii\helpers\BaseJson
Subclassesyii\helpers\Json
自版本起可用2.0
原始碼 https://github.com/yiisoft/yii2/blob/master/framework/helpers/BaseJson.php

BaseJson 為 yii\helpers\Json 提供具體實作。

請勿使用 BaseJson。請改用 yii\helpers\Json

公開屬性

隱藏繼承的屬性

屬性 類型 描述 定義於
$jsonErrorMessages array JSON 錯誤訊息列表,已指定給常數名稱,以便更佳地處理 PHP <= 5.5 的版本。 yii\helpers\BaseJson
$keepObjectType boolean 避免將索引從零開始的鍵值的物件編碼為陣列。Json::encode((object)['test']) 將被編碼為物件,而不是陣列。這與 json_encode() 的行為一致。 yii\helpers\BaseJson
$prettyPrint boolean|null 啟用人類可讀的輸出,又稱「美化輸出」。 yii\helpers\BaseJson

Public Methods

Hide inherited methods

Method 描述 定義於
decode() 將給定的 JSON 字串解碼為 PHP 資料結構。 yii\helpers\BaseJson
encode() 將給定的值編碼為 JSON 字串。 yii\helpers\BaseJson
errorSummary() 產生驗證錯誤的摘要。 yii\helpers\BaseJson
htmlEncode() 將給定的值編碼為 JSON 字串,並對 HTML 實體進行跳脫,使其可以安全地嵌入在 HTML 程式碼中。 yii\helpers\BaseJson

Protected Methods

Hide inherited methods

Method 描述 定義於
handleJsonError() 處理 encode()decode() 的錯誤,透過拋出包含各自錯誤訊息的例外來處理。 yii\helpers\BaseJson
processData() 在將資料傳送至 json_encode() 之前,先預處理資料。 yii\helpers\BaseJson

Property Details

隱藏繼承的屬性

$jsonErrorMessages public static property (自 2.0.7 版本起可用)

JSON 錯誤訊息列表,已指定給常數名稱,以便更佳地處理 PHP <= 5.5 的版本。

public static array $jsonErrorMessages = [
    
'JSON_ERROR_SYNTAX' => '語法錯誤',
    
'JSON_ERROR_UNSUPPORTED_TYPE' => '不支援的類型',
    
'JSON_ERROR_DEPTH' => '已超過堆疊最大深度',
    
'JSON_ERROR_STATE_MISMATCH' => 'JSON 無效或格式錯誤',
    
'JSON_ERROR_CTRL_CHAR' => '控制字元錯誤,可能編碼不正確',
    
'JSON_ERROR_UTF8' => 'UTF-8 字元格式錯誤,可能編碼不正確',
]
$keepObjectType public static property (自 2.0.44 版本起可用)

避免將索引從零開始的鍵值的物件編碼為陣列。Json::encode((object)['test']) 將被編碼為物件,而不是陣列。這與 json_encode() 的行為一致。預設值為 false,以避免任何向後相容性問題。針對單一用途啟用:Json::$keepObjectType = true;

另請參閱 yii\web\JsonResponseFormatter 文件,以針對所有 JSON 回應啟用此功能。

public static boolean $keepObjectType false
$prettyPrint public static property (自 2.0.43 版本起可用)

啟用人類可讀的輸出,又稱美化列印。這在開發期間進行偵錯時可能很有用,但不建議在生產環境中使用!若 prettyPrintnull (預設值),則傳遞給 encode 函式的 options 將不會變更。

public static boolean|null $prettyPrint null

Method Details

Hide inherited methods

decode() public static method

將給定的 JSON 字串解碼為 PHP 資料結構。

public static mixed decode ( $json, $asArray true )
$json string

要解碼的 JSON 字串

$asArray boolean

是否要以關聯陣列的形式傳回物件。

return mixed

PHP 資料

throws yii\base\InvalidArgumentException

若有任何解碼錯誤

                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;
}

            
encode() public static method

將給定的值編碼為 JSON 字串。

此方法透過支援 JavaScript 表達式來增強 json_encode() 的功能。特別是,此方法不會編碼以 yii\web\JsExpression 物件表示的 JavaScript 表達式。

請注意,根據 JSON 規範,編碼為 JSON 的資料必須是 UTF-8 編碼。您必須確保傳遞給此方法的字串在傳遞之前已正確編碼。

public static string encode ( $value, $options 320 )
$value mixed

要編碼的資料。

$options integer

編碼選項。如需更多詳細資訊,請參閱 https://php.dev.org.tw/manual/en/function.json-encode.php。預設值為 JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE

return string

編碼結果。

throws yii\base\InvalidArgumentException

若有任何編碼錯誤。

                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);
}

            
errorSummary() public static method (自 2.0.14 版本起可用)

產生驗證錯誤的摘要。

public static string errorSummary ( $models, $options = [] )
$models yii\base\Model|yii\base\Model[]

要顯示驗證錯誤的模型。

$options array

標籤選項,以名稱-值配對的形式表示。以下選項會特別處理

  • showAllErrors: boolean,若設為 true,則會顯示每個屬性的每個錯誤訊息,否則只會顯示每個屬性的第一個錯誤訊息。預設值為 false
return string

產生的錯誤摘要

                public static function errorSummary($models, $options = [])
{
    $showAllErrors = ArrayHelper::remove($options, 'showAllErrors', false);
    $lines = self::collectErrors($models, $showAllErrors);
    return static::encode($lines);
}

            
handleJsonError() protected static method (自 2.0.6 版本起可用)

處理 encode()decode() 的錯誤,透過拋出包含各自錯誤訊息的例外來處理。

protected static void handleJsonError ( $lastError )
$lastError integer

來自 json_last_error() 的錯誤代碼。

throws yii\base\InvalidArgumentException

若有任何編碼/解碼錯誤。

                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.');
}

            
htmlEncode() public static method (自 2.0.4 版本起可用)

將給定的值編碼為 JSON 字串,並對 HTML 實體進行跳脫,使其可以安全地嵌入在 HTML 程式碼中。

此方法透過支援 JavaScript 表達式來增強 json_encode() 的功能。特別是,此方法不會編碼以 yii\web\JsExpression 物件表示的 JavaScript 表達式。

請注意,根據 JSON 規範,編碼為 JSON 的資料必須是 UTF-8 編碼。您必須確保傳遞給此方法的字串在傳遞之前已正確編碼。

public static string htmlEncode ( $value )
$value mixed

要編碼的資料

return string

編碼結果

throws yii\base\InvalidArgumentException

若有任何編碼錯誤

                public static function htmlEncode($value)
{
    return static::encode($value, JSON_UNESCAPED_UNICODE | JSON_HEX_QUOT | JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS);
}

            
processData() protected static method

在將資料傳送至 json_encode() 之前,先預處理資料。

protected static mixed processData ( $data, &$expressions, $expPrefix )
$data mixed

要處理的資料

$expressions array

JavaScript 表達式集合

$expPrefix string

內部用於處理 JS 表達式的前綴

return mixed

已處理的資料

                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;
}