feat: allow JSON normalizer to set JSON formatting options

By default, the JSON normalizer will only use `JSON_THROW_ON_ERROR` to
encode non-boolean scalar values. There might be use-cases where
projects will need flags like `JSON_JSON_PRESERVE_ZERO_FRACTION`.

This can be achieved by passing these flags to the new
`JsonNormalizer::withOptions()` method:

```php
namespace My\App;

$normalizer = (new \CuyZ\Valinor\MapperBuilder())
    ->normalizer(\CuyZ\Valinor\Normalizer\Format::json())
    ->withOptions(\JSON_PRESERVE_ZERO_FRACTION);

$lowerManhattanAsJson = $normalizer->normalize(
    new \My\App\Coordinates(
        longitude: 40.7128,
        latitude: -74.0000
    )
);

// `$lowerManhattanAsJson` is a valid JSON string representing the data:
// {"longitude":40.7128,"latitude":-74.0000}
```

The method accepts an int-mask of the following `JSON_*` constant
representations:

- `JSON_HEX_QUOT`
- `JSON_HEX_TAG`
- `JSON_HEX_AMP`
- `JSON_HEX_APOS`
- `JSON_INVALID_UTF8_IGNORE`
- `JSON_INVALID_UTF8_SUBSTITUTE`
- `JSON_NUMERIC_CHECK`
- `JSON_PRESERVE_ZERO_FRACTION`
- `JSON_UNESCAPED_LINE_TERMINATORS`
- `JSON_UNESCAPED_SLASHES`
- `JSON_UNESCAPED_UNICODE`

`JSON_THROW_ON_ERROR` is always enforced and thus is not accepted.

See official doc for more information:
https://www.php.net/manual/en/json.constants.php

docs/pages/serialization/normalizing-json.md

@@ -72,8 +72,54 @@ $normalizer = (new \CuyZ\Valinor\MapperBuilder())
 $normalizer->normalize($users);
 ```
 
+## Passing `json_encode` flags
+
+By default, the JSON normalizer will only use `JSON_THROW_ON_ERROR` to encode
+non-boolean scalar values. There might be use-cases where projects will need
+flags like `JSON_JSON_PRESERVE_ZERO_FRACTION`.
+
+This can be achieved by passing these flags to the
+`JsonNormalizer::withOptions()` method:
+
+```php
+namespace My\App;
+
+$normalizer = (new \CuyZ\Valinor\MapperBuilder())
+ ->normalizer(\CuyZ\Valinor\Normalizer\Format::json())
+ ->withOptions(\JSON_PRESERVE_ZERO_FRACTION);
+
+$lowerManhattanAsJson = $normalizer->normalize(
+ new \My\App\Coordinates(
+ longitude: 40.7128,
+ latitude: -74.0000
+ )
+);
+
+// `$lowerManhattanAsJson` is a valid JSON string representing the data:
+// {"longitude":40.7128,"latitude":-74.0000}
+```
+
+The method accepts an int-mask of the following `JSON_*` constant
+representations ([see official doc for more information]):
+
+- `JSON_HEX_QUOT`
+- `JSON_HEX_TAG`
+- `JSON_HEX_AMP`
+- `JSON_HEX_APOS`
+- `JSON_INVALID_UTF8_IGNORE`
+- `JSON_INVALID_UTF8_SUBSTITUTE`
+- `JSON_NUMERIC_CHECK`
+- `JSON_PRESERVE_ZERO_FRACTION`
+- `JSON_UNESCAPED_LINE_TERMINATORS`
+- `JSON_UNESCAPED_SLASHES`
+- `JSON_UNESCAPED_UNICODE`
+
+`JSON_THROW_ON_ERROR` is always enforced and thus is not accepted.
+
 [default transformations]: normalizer.md#supported-transformations
 
 [registered transformers]: extending-normalizer.md
 
 [can be streamed to a PHP resource]: #streaming-to-a-php-resource
+
+[see official doc for more information]: https://www.php.net/manual/en/json.constants.php

src/Normalizer/Formatter/JsonFormatter.php

@@ -16,6 +16,8 @@
 use function is_scalar;
 use function json_encode;
 
+use const JSON_THROW_ON_ERROR;
+
 /** @internal */
 final class JsonFormatter implements StreamFormatter
 {
@@ -24,6 +26,7 @@ final class JsonFormatter implements StreamFormatter
  */
  public function __construct(
  private mixed $resource,
+ private int $jsonEncodingOptions,
  ) {}
 
  public function format(mixed $value): void
@@ -33,7 +36,11 @@ public function format(mixed $value): void
  } elseif (is_bool($value)) {
  $this->write($value ? 'true' : 'false');
  } elseif (is_scalar($value)) {
- $this->write(json_encode($value, JSON_THROW_ON_ERROR));
+ /**
+ * @phpstan-ignore-next-line / Due to the new json encoding options feature, it is not possible to let SA
+ * tools understand that JSON_THROW_ON_ERROR is always set.
+ */
+ $this->write(json_encode($value, $this->jsonEncodingOptions));
  } elseif (is_iterable($value)) {
  // Note: when a generator is formatted, it is considered as a list
  // if its first key is 0. This is done early because the first JSON
@@ -59,7 +66,9 @@ public function format(mixed $value): void
  $isFirst = false;
 
  if (! $isList) {
- $this->write('"' . $key . '":');
+ $key = json_encode((string)$key, $this->jsonEncodingOptions);
+
+ $this->write($key . ':');
  }
 
  $this->format($val);

src/Normalizer/JsonNormalizer.php

@@ -6,7 +6,6 @@
 
 use CuyZ\Valinor\Normalizer\Formatter\JsonFormatter;
 use CuyZ\Valinor\Normalizer\Transformer\RecursiveTransformer;
-
 use RuntimeException;
 
 use function fclose;
@@ -15,16 +14,91 @@
 use function is_resource;
 use function stream_get_contents;
 
+use const JSON_HEX_AMP;
+use const JSON_HEX_APOS;
+use const JSON_HEX_QUOT;
+use const JSON_HEX_TAG;
+use const JSON_INVALID_UTF8_IGNORE;
+use const JSON_INVALID_UTF8_SUBSTITUTE;
+use const JSON_NUMERIC_CHECK;
+use const JSON_PRESERVE_ZERO_FRACTION;
+use const JSON_THROW_ON_ERROR;
+use const JSON_UNESCAPED_LINE_TERMINATORS;
+use const JSON_UNESCAPED_SLASHES;
+use const JSON_UNESCAPED_UNICODE;
+
 /**
  * @api
  *
  * @implements Normalizer<string>
  */
 final class JsonNormalizer implements Normalizer
 {
+ private const ACCEPTABLE_JSON_OPTIONS = JSON_HEX_QUOT
+ | JSON_HEX_TAG
+ | JSON_HEX_AMP
+ | JSON_HEX_APOS
+ | JSON_INVALID_UTF8_IGNORE
+ | JSON_INVALID_UTF8_SUBSTITUTE
+ | JSON_NUMERIC_CHECK
+ | JSON_PRESERVE_ZERO_FRACTION
+ | JSON_UNESCAPED_LINE_TERMINATORS
+ | JSON_UNESCAPED_SLASHES
+ | JSON_UNESCAPED_UNICODE
+ | JSON_THROW_ON_ERROR;
+
+ private RecursiveTransformer $transformer;
+
+ private int $jsonEncodingOptions;
+
+ /**
+ * Internal note
+ * -------------
+ *
+ * We could use the `int-mask-of<JsonNormalizer::JSON_*>` annotation
+ * to let PHPStan infer the type of the accepted options, but some caveats
+ * were found:
+ * - SA tools are not able to infer that we end up having only accepted
+ * options. Might be fixed with https://github.com/phpstan/phpstan/issues/9384
+ * for PHPStan but Psalm does have some (not all) issues as well.
+ * - Using this annotation provokes *severe* performance issues when
+ * running PHPStan analysis, therefore it is preferable to avoid it.
+ */
  public function __construct(
- private RecursiveTransformer $transformer,
- ) {}
+ RecursiveTransformer $transformer,
+ int $jsonEncodingOptions = JSON_THROW_ON_ERROR,
+ ) {
+ $this->transformer = $transformer;
+ $this->jsonEncodingOptions = (self::ACCEPTABLE_JSON_OPTIONS & $jsonEncodingOptions) | JSON_THROW_ON_ERROR;
+ }
+
+ /**
+ * By default, the JSON normalizer will only use `JSON_THROW_ON_ERROR` to
+ * encode non-boolean scalar values. There might be use-cases where projects
+ * will need flags like `JSON_JSON_PRESERVE_ZERO_FRACTION`.
+ *
+ * This can be achieved by passing these flags to this method:
+ *
+ * ```php
+ * $normalizer = (new \CuyZ\Valinor\MapperBuilder())
+ * ->normalizer(\CuyZ\Valinor\Normalizer\Format::json())
+ * ->withOptions(\JSON_PRESERVE_ZERO_FRACTION);
+ *
+ * $lowerManhattanAsJson = $normalizer->normalize(
+ * new \My\App\Coordinates(
+ * longitude: 40.7128,
+ * latitude: -74.0000
+ * )
+ * );
+ *
+ * // `$lowerManhattanAsJson` is a valid JSON string representing the data:
+ * // {"longitude":40.7128,"latitude":-74.0000}
+ * ```
+ */
+ public function withOptions(int $options): self
+ {
+ return new self($this->transformer, $options);
+ }
 
  public function normalize(mixed $value): string
  {
@@ -33,7 +107,7 @@ public function normalize(mixed $value): string
  /** @var resource $resource */
  $resource = fopen('php://memory', 'w');
 
- (new JsonFormatter($resource))->format($value);
+ (new JsonFormatter($resource, $this->jsonEncodingOptions))->format($value);
 
  rewind($resource);
 
@@ -80,6 +154,6 @@ public function streamTo(mixed $resource): StreamNormalizer
  throw new RuntimeException('Expected a valid resource, got ' . get_debug_type($resource));
  }
 
- return new StreamNormalizer($this->transformer, new JsonFormatter($resource));
+ return new StreamNormalizer($this->transformer, new JsonFormatter($resource, $this->jsonEncodingOptions));
  }
 }

tests/Integration/Normalizer/NormalizerTest.php

@@ -29,6 +29,9 @@
 
 use function array_merge;
 
+use const JSON_HEX_TAG;
+use const JSON_THROW_ON_ERROR;
+
 final class NormalizerTest extends IntegrationTestCase
 {
  /**
@@ -42,6 +45,7 @@ public function test_normalize_basic_values_yields_expected_output(
  string $expectedJson,
  array $transformers = [],
  array $transformerAttributes = [],
+ int $jsonEncodingOptions = JSON_THROW_ON_ERROR,
  ): void {
  $builder = $this->mapperBuilder();
 
@@ -56,7 +60,9 @@ public function test_normalize_basic_values_yields_expected_output(
  }
 
  $arrayResult = $builder->normalizer(Format::array())->normalize($input);
- $jsonResult = $builder->normalizer(Format::json())->normalize($input);
+ $jsonNormalizer = $builder->normalizer(Format::json())->withOptions($jsonEncodingOptions);
+
+ $jsonResult = $jsonNormalizer->normalize($input);
 
  self::assertSame($expectedArray, $arrayResult);
  self::assertSame($expectedJson, $jsonResult);
@@ -141,18 +147,20 @@ public static function normalize_basic_values_yields_expected_output_data_provid
 
  yield 'array of scalar' => [
  'input' => [
+ 0 => 'first value',
  'string' => 'foo',
  'integer' => 42,
  'float' => 1337.404,
  'boolean' => true,
  ],
  'expected array' => [
+ 0 => 'first value',
  'string' => 'foo',
  'integer' => 42,
  'float' => 1337.404,
  'boolean' => true,
  ],
- 'expected json' => '{"string":"foo","integer":42,"float":1337.404,"boolean":true}',
+ 'expected json' => '{"0":"first value","string":"foo","integer":42,"float":1337.404,"boolean":true}',
  ];
 
  yield 'array with transformer' => [
@@ -303,13 +311,13 @@ public function getIterator(): Traversable
  ];
 
  yield 'date with default transformer' => [
- 'input' => new DateTimeImmutable('1971-11-08'),
+ 'input' => new DateTimeImmutable('1971-11-08', new DateTimeZone('UTC')),
  'expected array' => '1971-11-08T00:00:00.000000+00:00',
  'expected json' => '"1971-11-08T00:00:00.000000+00:00"',
  ];
 
  yield 'date with transformer' => [
- 'input' => new DateTimeImmutable('1971-11-08'),
+ 'input' => new DateTimeImmutable('1971-11-08', new DateTimeZone('UTC')),
  'expected array' => '1971-11-08',
  'expected json' => '"1971-11-08"',
  'transformers' => [
@@ -641,6 +649,28 @@ public function __construct(
  SomeKeyTransformerInterface::class,
  ],
  ];
+
+ yield 'object with float property containing zero fraction' => [
+ 'input' => new class () {
+ public function __construct(
+ public float $value = 1.0,
+ ) {}
+ },
+ 'expected array' => ['value' => 1.0],
+ 'expected_json' => '{"value":1.0}',
+ 'transformers' => [],
+ 'transformerAttributes' => [],
+ 'jsonEncodingOptions' => JSON_PRESERVE_ZERO_FRACTION,
+ ];
+
+ yield 'array with key and value containing ampersand' => [
+ 'input' => ['foo&bar' => 'bar&baz'],
+ 'expected array' => ['foo&bar' => 'bar&baz'],
+ 'expected_json' => '{"foo\u0026bar":"bar\u0026baz"}',
+ 'transformers' => [],
+ 'transformerAttributes' => [],
+ 'jsonEncodingOptions' => JSON_HEX_AMP,
+ ];
  }
 
  public function test_generator_of_scalar_yields_expected_array(): void
@@ -1036,6 +1066,33 @@ public function test_giving_invalid_resource_to_json_normalizer_throws_exception
  // @phpstan-ignore-next-line
  $this->mapperBuilder()->normalizer(Format::json())->streamTo('foo');
  }
+
+ public function test_json_transformer_will_always_throw_on_error(): void
+ {
+ $normalizer = $this->mapperBuilder()->normalizer(Format::json());
+ self::assertSame(JSON_THROW_ON_ERROR, (fn () => $this->jsonEncodingOptions)->call($normalizer));
+
+ $normalizer = $normalizer->withOptions(JSON_HEX_TAG);
+ self::assertSame(JSON_THROW_ON_ERROR | JSON_HEX_TAG, (fn () => $this->jsonEncodingOptions)->call($normalizer));
+
+ $normalizer = $normalizer->withOptions(JSON_HEX_TAG & ~JSON_THROW_ON_ERROR);
+ self::assertSame(JSON_THROW_ON_ERROR | JSON_HEX_TAG, (fn () => $this->jsonEncodingOptions)->call($normalizer));
+ }
+
+ public function test_json_transformer_only_accepts_acceptable_json_options(): void
+ {
+ $normalizer = $this->mapperBuilder()->normalizer(Format::json())->withOptions(JSON_FORCE_OBJECT);
+ self::assertSame(JSON_THROW_ON_ERROR, (fn () => $this->jsonEncodingOptions)->call($normalizer));
+
+ $normalizer = $this->mapperBuilder()->normalizer(Format::json())->withOptions(JSON_PARTIAL_OUTPUT_ON_ERROR);
+ self::assertSame(JSON_THROW_ON_ERROR, (fn () => $this->jsonEncodingOptions)->call($normalizer));
+
+ $normalizer = $this->mapperBuilder()->normalizer(Format::json())->withOptions(JSON_PRETTY_PRINT);
+ self::assertSame(JSON_THROW_ON_ERROR, (fn () => $this->jsonEncodingOptions)->call($normalizer));
+
+ $normalizer = $this->mapperBuilder()->normalizer(Format::json())->withOptions(JSON_FORCE_OBJECT | JSON_PARTIAL_OUTPUT_ON_ERROR | JSON_PRETTY_PRINT);
+ self::assertSame(JSON_THROW_ON_ERROR, (fn () => $this->jsonEncodingOptions)->call($normalizer));
+ }
 }
 
 final class BasicObject

tests/Unit/Normalizer/Formatter/JsonFormatterTest.php

@@ -10,6 +10,8 @@
 
 use function fopen;
 
+use const JSON_THROW_ON_ERROR;
+
 final class JsonFormatterTest extends TestCase
 {
  public function test_invalid_closure_type_given_to_formatter_throws_exception(): void
@@ -21,6 +23,6 @@ public function test_invalid_closure_type_given_to_formatter_throws_exception():
  /** @var resource $resource */
  $resource = fopen('php://memory', 'r+');
 
- (new JsonFormatter($resource))->format(fn () => 42);
+ (new JsonFormatter($resource, JSON_THROW_ON_ERROR))->format(fn () => 42);
  }
 }