diff --git a/docs/guide/README.md b/docs/guide/README.md index a802d3024e..5d29cfc00c 100644 --- a/docs/guide/README.md +++ b/docs/guide/README.md @@ -201,5 +201,6 @@ Helpers * [Helpers Overview](helper-overview.md) * [ArrayHelper](helper-array.md) * [Html](helper-html.md) +* [Json](helper-json.md) * [Url](helper-url.md) diff --git a/docs/guide/helper-json.md b/docs/guide/helper-json.md new file mode 100644 index 0000000000..c8aed96f12 --- /dev/null +++ b/docs/guide/helper-json.md @@ -0,0 +1,26 @@ +Json Helper +========== + +Json helper provides a set of static methods for encoding and decoding JSON. +It handles encoding errors and the `[[yii\helpers\Json::encode()]]` method will not encode a JavaScript expression that is represented in +terms of a `[[yii\web\JsExpression]]` object. +By default, ecoding is done with the `JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE` options. +Please see [PHP:json_encode](https://secure.php.net/manual/en/function.json-encode.php) for more information. + +## Pretty Print + +By default the `[[yii\helpers\Json::encode()]]` method will output unformatted JSON (e.g. without whitespaces). +To make it more readable for humans you can turn on "pretty printing". + +> Note: Pretty Print can useful for debugging during development but is not recommended in a production environment. + +To enable pretty print in a single instance you can specify it as an option. E.g. + +```php +$data = ['a' => 1, 'b' => 2]; +$json = yii\helpers\Json::encode($data, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT); +``` +You can also enable pretty printing of the JSON helper globally. For example in your config for or index.php: +```php +yii\helpers\Json::$prettyPrint = YII_DEBUG; // use "pretty" output in debug mode +``` diff --git a/docs/guide/helper-overview.md b/docs/guide/helper-overview.md index f6f85c357a..087b7657f5 100644 --- a/docs/guide/helper-overview.md +++ b/docs/guide/helper-overview.md @@ -33,7 +33,7 @@ The following core helper classes are provided in the Yii releases: - HtmlPurifier - Imagine (provided by yii2-imagine extension) - Inflector -- Json +- [Json](helper-json.md) - Markdown - StringHelper - [Url](helper-url.md) diff --git a/framework/CHANGELOG.md b/framework/CHANGELOG.md index 0c4c5cf6f0..fbe1ff7587 100644 --- a/framework/CHANGELOG.md +++ b/framework/CHANGELOG.md @@ -12,6 +12,7 @@ Yii Framework 2 Change Log - Enh #18676: Added method `yii\helpers\BaseFileHelper::changeOwnership()` and properties `newFileMode`/`newFileOwnership` in `yii\console\controllers\BaseMigrateController` (rhertogh) - Bug #18678: Fix `yii\caching\DbCache` to use configured cache table name instead of the default one in case of MSSQL varbinary column type detection (aidanbek) - Enh #18695: Added `yii\web\Cookie::SAME_SITE_NONE` constant (rhertogh) +- Enh #18726: Added `yii\helpers\Json::$prettyPrint` (rhertogh) 2.0.42.1 May 06, 2021 diff --git a/framework/helpers/BaseJson.php b/framework/helpers/BaseJson.php index 0e3663e4a2..2637653e84 100644 --- a/framework/helpers/BaseJson.php +++ b/framework/helpers/BaseJson.php @@ -22,6 +22,13 @@ use yii\base\Model; */ class BaseJson { + /** + * @var bool|null 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. + * @since 2.0.43 + */ + public static $prettyPrint = null; /** * List of JSON Error messages assigned to constant names for better handling of version differences. * @var array @@ -62,6 +69,13 @@ class BaseJson 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()); diff --git a/tests/framework/helpers/JsonTest.php b/tests/framework/helpers/JsonTest.php index 785b093ea3..9695af91c0 100644 --- a/tests/framework/helpers/JsonTest.php +++ b/tests/framework/helpers/JsonTest.php @@ -230,6 +230,37 @@ class JsonTest extends TestCase $output = Json::encode($input); $this->assertEquals('{"date":"2014-10-12 00:00:00.000000","timezone_type":3,"timezone":"UTC"}', $output); } + + public function testPrettyPrint() + { + $defaultValue = Json::$prettyPrint; + $input = ['a' => 1, 'b' => 2]; + $defOutput = '{"a":1,"b":2}'; + $ppOutput = "{\n \"a\": 1,\n \"b\": 2\n}"; + + // Test unchanged options + Json::$prettyPrint = null; + $output = Json::encode($input, 320); + $this->assertEquals($defOutput, $output); + $output = Json::encode($input, 448); + $this->assertEquals($ppOutput, $output); + + // Test pretty print enabled + Json::$prettyPrint = true; + $output = Json::encode($input, 320); + $this->assertEquals($ppOutput, $output); + $output = Json::encode($input, 448); + $this->assertEquals($ppOutput, $output); + + // Test pretty print disabled + Json::$prettyPrint = false; + $output = Json::encode($input, 320); + $this->assertEquals($defOutput, $output); + $output = Json::encode($input, 448); + $this->assertEquals($defOutput, $output); + + Json::$prettyPrint = $defaultValue; + } } class JsonModel extends DynamicModel implements \JsonSerializable