Merge pull request #237 from gsteel/json-view-helper-v2

Deprecate the JSON View Helper for Removal in v3.0

docs/book/v2/helpers/json.md

@@ -1,5 +1,9 @@
 # Json
 
+WARNING: **Deprecated**
+The JSON view helper has been deprecated and will be removed in version 3.0.
+There is no replacement; however, it is trivial to encode data by using PHP's built-in [`json_encode`](https://www.php.net/json_encode) function. 
+
 When creating views that return JSON, it's important to also set the appropriate
 response header. The JSON view helper does exactly that. In addition, by
 default, it disables layouts (if currently enabled), as layouts generally aren't
@@ -20,28 +24,13 @@ determine how to handle the content.
 <?= $this->json($this->data) ?>
 ```
 
-> WARNING: **Deprecated**
->
-> ### Enabling encoding using Laminas\Json\Expr
->
-> **This feature of the Json view helper has been deprecated in version 2.16 and will be removed in version 3.0.**
->
-> The JSON helper accepts an array of options that will be passed to `Laminas\Json\Json::encode()` and
-> used internally to encode data.
-> `Laminas\Json\Json::encode` allows the encoding of native JSON expressions using `Laminas\Json\Expr`
-> objects. This option is disabled by default. To enable this option, pass a boolean `true` to the
-> `enableJsonExprFinder` key of the options array:
->
-> ```php
-> <?= $this->json($this->data, ['enableJsonExprFinder' => true]) ?>
-> ``
->
-> The JSON helper accepts an array of options that will be passed to `Laminas\Json\Json::encode()` and
-> used internally to encode data.
-> `Laminas\Json\Json::encode` allows the encoding of native JSON expressions using `Laminas\Json\Expr`
-> objects. This option is disabled by default. To enable this option, pass a boolean `true` to the
-> `enableJsonExprFinder` key of the options array:
->
-> ```php
-> <?= $this->json($this->data, ['enableJsonExprFinder' => true]) ?>
-> ```
+### Enabling encoding using Laminas\Json\Expr
+
+The JSON helper accepts an array of options that will be passed to `Laminas\Json\Json::encode()` and used internally to encode data.
+`Laminas\Json\Json::encode` allows the encoding of native JSON expressions using `Laminas\Json\Expr` objects.
+This option is disabled by default.
+To enable this option, pass a boolean `true` to the `enableJsonExprFinder` key of the options array:
+
+```php
+<?= $this->json($this->data, ['enableJsonExprFinder' => true]) ?>
+```

docs/book/v2/migration/preparing-for-v3.md

@@ -30,7 +30,7 @@ try {
 }
 ```
 
-## Deprecations 
+## Deprecations
 
 ### Undocumented Behaviour
 
@@ -44,3 +44,11 @@ This deprecation can be safely ignored but in order to prepare for its removal i
 In version 2, the `TemplatePathStack` template resolver automatically registers a stream wrapper for templates when the php.ini setting `short_open_tag` was turned off. The purpose of the stream wrapper was to convert template files using the short open tag `<?= $variable ?>` to `<?php echo $variable ?>` so that templates would continue to be processed in environments where short_open_tag was turned off. Since PHP 5.4.0, `<?=` is always available, therefore the wrapper became mostly unnecessary.
 
 The impact of this future removal will affect templates that use a regular short open tag for general PHP code, i.e. `<? $i = 1; echo $i ?>` in environments where `short_open_tag` is **off**. To mitigate the impact of this removal, you should ensure that, where relevant, all of your templates use the full `<?php` open tag. Use of the short echo tag `<?=` is unaffected.
+
+## View Helper Changes
+
+### Deprecated View Helpers Scheduled for Removal in 3.0 
+
+The following view helpers are deprecated and will be removed in version 3.0 of `laminas-view`.
+
+- The [Json View Helper](../helpers/json.md)

psalm-baseline.xml

@@ -104,6 +104,11 @@
  <code>vars</code>
  </UndefinedInterfaceMethod>
  </file>
+ <file src="src/Helper/DeprecatedAbstractHelperHierarchyTrait.php">
+ <DeprecatedClass>
+ <code>self</code>
+ </DeprecatedClass>
+ </file>
  <file src="src/Helper/Doctype.php">
  <DocblockTypeContradiction>
  <code>null === static::$registeredDoctypes</code>

src/Helper/Json.php

@@ -14,6 +14,8 @@
 /**
  * Helper for simplifying JSON responses
  *
+ * @deprecated This view helper is obsolete and will be removed in version 3.0
+ *
  * @psalm-suppress DeprecatedProperty
  * @final
  */

test/Helper/JsonTest.php

@@ -11,11 +11,19 @@
 use Laminas\View\Helper\Json as JsonHelper;
 use PHPUnit\Framework\TestCase;
 
+use function json_encode;
 use function restore_error_handler;
 use function set_error_handler;
 
 use const E_USER_DEPRECATED;
+use const JSON_PRETTY_PRINT;
+use const JSON_THROW_ON_ERROR;
 
+/**
+ * @deprecated To be removed with the Json View Helper in v3.0
+ *
+ * @psalm-suppress DeprecatedClass
+ */
 class JsonTest extends TestCase
 {
  private Response $response;
@@ -74,4 +82,14 @@ public function testThatADeprecationErrorIsNotTriggeredWhenExpressionFinderOptio
  $this->expectNotToPerformAssertions();
  $this->helper->__invoke(['foo'], ['enableJsonExprFinder' => 'anything other than true']);
  }
+
+ public function testTheHelperWillPrettyPrintWhenRequired(): void
+ {
+ $input = [
+ 'dory' => 'blue',
+ 'nemo' => 'orange',
+ ];
+ $expect = json_encode($input, JSON_THROW_ON_ERROR | JSON_PRETTY_PRINT);
+ self::assertSame($expect, ($this->helper)->__invoke($input, ['prettyPrint' => true]));
+ }
 }