Provides generic and vendor-specific normalizers for normalizing JSON documents.
Run
$ composer require ergebnis/json-normalizer
This package comes with the following generic normalizers:
Ergebnis\Json\Normalizer\AutoFormatNormalizer
Ergebnis\Json\Normalizer\CallableNormalizer
Ergebnis\Json\Normalizer\ChainNormalizer
Ergebnis\Json\Normalizer\FixedFormatNormalizer
Ergebnis\Json\Normalizer\IndentNormalizer
Ergebnis\Json\Normalizer\JsonEncodeNormalizer
Ergebnis\Json\Normalizer\SchemaNormalizer
Ergebnis\Json\Normalizer\WithFinalNewLineNormalizer
Ergebnis\Json\Normalizer\WithoutFinalNewLineNormalizer
💡 All of these normalizers implement the Ergebnis\Json\Normalizer\NormalizerInterface
.
When you want to normalize a JSON file with an implementation of NormalizerInterface
, but retain the original formatting, you can use the AutoFormatNormalizer
.
<?php
use Ergebnis\Json\Normalizer;
use Ergebnis\Json\Printer;
$encoded = <<<'JSON'
{
"name": "Andreas Möller",
"url": "https://localheinz.com"
}
JSON;
$json = Normalizer\Json::fromEncoded($encoded);
/*- @var Normalizer\NormalizerInterface $composedNormalizer*/
$normalizer = new Normalizer\AutoFormatNormalizer(
$composedNormalizer,
new Normalizer\Format\Formatter(new Printer\Printer())
);
$normalized = $normalizer->normalize($json);
The normalized version will now have the composed normalizer applied, but also retained the original formatting (within certain limits). Before applying the composer normalizer, the AutoFormatNormalizer
will attempt to detect the following:
json_encode()
options- indent
- whether a final new line exists or not
After applying the composed normalizer, the AutoFormatNormalizer
will
- decode with
json_decode()
and encode again withjson_encode()
, passing in the previously detected options - indent with the detected indent
- add a final new line of detected
💡 Alternatively, you can use the FixedFormatNormalizer
.
When you want to normalize a JSON file with a callable
, you can use the CallableNormalizer
.
<?php
use Ergebnis\Json\Normalizer;
$encoded = <<<'JSON'
{
"name": "Andreas Möller",
"url": "https://localheinz.com"
}
JSON;
$json = Normalizer\Json::fromEncoded($encoded);
$callable = function (Normalizer\Json $json): Normalizer\Json {
$decoded = $json->decoded();
foreach (get_object_vars($decoded) as $name => $value) {
if ('https://localheinz.com' !== $value) {
continue;
}
$decoded->{$name} .= '/open-source/';
}
return Normalizer\Json::fromEncoded(json_encode($decoded));
};
$normalizer = new Normalizer\CallableNormalizer($callable);
$normalized = $normalizer->normalize($json);
The normalized version will now have the callable applied to it.
When you want to apply multiple normalizers in a chain, you can use the ChainNormalizer
.
<?php
use Ergebnis\Json\Normalizer;
use Ergebnis\Json\Printer;
$encoded = <<<'JSON'
{
"name": "Andreas Möller",
"url": "https://localheinz.com"
}
JSON;
$json = Normalizer\Json::fromEncoded($encoded);
$indent = Normalizer\Format\Indent::fromString(' ');
$jsonEncodeOptions = Normalizer\Format\JsonEncodeOptions::fromInt(JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
$normalizer = new Normalizer\ChainNormalizer(
new Normalizer\JsonEncodeNormalizer($jsonEncodeOptions),
new Normalizer\IndentNormalizer(
$indent,
new Printer\Printer()
),
new Normalizer\WithFinalNewLineNormalizer()
);
$normalized = $normalizer->normalize($json);
The normalized version will now contain the result of applying all normalizers in a chain, one after another.
💡 Be careful with the order of the normalizers, as one normalizer might override changes a previous normalizer applied.
When you want to normalize a JSON file with an implementation of NormalizerInterface
, but apply a fixed formatting, you can use the FixedFormatNormalizer
.
<?php
use Ergebnis\Json\Normalizer;
use Ergebnis\Json\Printer;
$encoded = <<<'JSON'
{
"name": "Andreas Möller",
"url": "https://localheinz.com"
}
JSON;
$json = Normalizer\Json::fromEncoded($encoded);
/*- @var Normalizer\NormalizerInterface $composedNormalizer*/
/*- @var Normalizer\Format\Format $format*/
$normalizer = new Normalizer\FixedFormatNormalizer(
$composedNormalizer,
$format,
new Normalizer\Format\Formatter(new Printer\Printer())
);
$normalized = $normalizer->normalize($json);
The normalized version will now have the composed normalizer applied, but also the formatting applied according to $format
.
💡 Alternatively, you can use the AutoFormatNormalizer
.
When you need to adjust the indentation of a JSON file, you can use the IndentNormalizer
.
<?php
use Ergebnis\Json\Normalizer;
use Ergebnis\Json\Printer;
$encoded = <<<'JSON'
{
"name": "Andreas Möller",
"url": "https://localheinz.com"
}
JSON;
$json = Normalizer\Json::fromEncoded($encoded);
$indent = Normalizer\Format\Indent::fromString(' ');
$normalizer = new Normalizer\IndentNormalizer(
$indent,
new Printer\Printer()
);
$normalized = $normalizer->normalize($json);
The normalized version will now be indented with 2 spaces.
When you need to adjust the encoding of a JSON file, you can use the JsonEncodeNormalizer
.
<?php
use Ergebnis\Json\Normalizer;
$encoded = <<<'JSON'
{
"name": "Andreas M\u00f6ller",
"url": "https:\/\/localheinz.com"
}
JSON;
$json = Normalizer\Json::fromEncoded($encoded);
$jsonEncodeOptions = Normalizer\Format\JsonEncodeOptions::fromInt(JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
$normalizer = new Normalizer\JsonEncodeNormalizer($jsonEncodeOptions);
$normalized = $normalizer->normalize($json);
The normalized version will now be encoded with $jsonEncodeOptions
.
💡 For reference, see json_encode()
and the corresponding JSON constants.
When you want to rebuild a JSON file according to a JSON schema, you can use the SchemaNormalizer
.
Let's assume the following schema
{
"type": "object",
"additionalProperties": true,
"properties": {
"name" : {
"type" : "string"
},
"role" : {
"type" : "string"
}
}
}
exists at /schema/example.json
.
<?php
use Ergebnis\Json\Normalizer;
use Ergebnis\Json\SchemaValidator;
use JsonSchema\SchemaStorage;
$encoded = <<<'JSON'
{
"url": "https://localheinz.com",
"name": "Andreas Möller",
"open-source-projects": {
"ergebnis/composer-normalize":
"downloads": {
"total": 5,
"monthly": 2
},
},
"ergebnis/data-provider": {
"downloads": {
"total": 2,
"monthly": 1
}
}
}
}
JSON;
$json = Normalizer\Json::fromEncoded($encoded);
$normalizer = new Normalizer\SchemaNormalizer(
'file:///schema/example.json',
new SchemaStorage(),
new SchemaValidator\SchemaValidator()
);
$normalized = $normalizer->normalize($json);
The normalized version will now be structured according to the JSON schema (in this simple case, properties will be reordered as found in the schema and additional properties will be ordered by name). Internally, the SchemaNormalizer
uses justinrainbow/json-schema
to resolve schemas, as well as to ensure (before and after normalization) that the JSON document is valid.
💡 For more information about JSON schema, visit json-schema.org.
When you want to ensure that a JSON file has a single final new line, you can use the WithFinalNewLineNormalizer
.
<?php
use Ergebnis\Json\Normalizer;
$encoded = <<<'JSON'
{
"name": "Andreas Möller",
"url": "https://localheinz.com"
}
JSON;
$json = Normalizer\Json::fromEncoded($encoded);
$normalizer = new Normalizer\WithFinalNewLineNormalizer();
$normalized = $normalizer->normalize($json);
The normalized version will now have a single final new line.
When you want to ensure that a JSON file does not have a final new line, you can use the WithoutFinalNewLineNormalizer
.
<?php
use Ergebnis\Json\Normalizer;
$encoded = <<<'JSON'
{
"name": "Andreas Möller",
"url": "https://localheinz.com"
}
JSON;
$json = Normalizer\Json::fromEncoded($encoded);
$normalizer = new Normalizer\WithoutFinalNewLineNormalizer();
$normalized = $normalizer->normalize($json);
The normalized version will now not have a final new line or any whitespace at the end.
This package comes with the following vendor-specific normalizers:
The Vendor\Composer\ComposerJsonNormalizer
can be used to normalize a composer.json
file according to its underlying JSON schema.
It composes the following normalizers:
Ergebnis\Composer\Json\Normalizer\Vendor\Composer\BinNormalizer
Ergebnis\Composer\Json\Normalizer\Vendor\Composer\ConfigHashNormalizer
Ergebnis\Composer\Json\Normalizer\Vendor\Composer\PackageHashNormalizer
Ergebnis\Composer\Json\Normalizer\Vendor\Composer\VersionConstraintNormalizer
When composer.json
contains an array of scripts in the bin
section, the Vendor\Composer\BinNormalizer
will sort the elements of the bin
section by value in ascending order.
💡 Find out more about the bin
section at Composer: The composer.json schema.
When composer.json
contains any configuration in the
config
extra
scripts-descriptions
sections, the Vendor\Composer\ConfigHashNormalizer
will sort the content of these sections by key in ascending order. If a value is an object, it will continue to sort its properties by name.
💡 Find out more about the config
section at Composer: The composer.json schema.
When composer.json
contains any configuration in the
conflict
provide
replace
require
require-dev
suggest
sections, the Vendor\Composer\PackageHashNormalizer
will sort the content of these sections.
💡 This transfers the behaviour from using the --sort-packages
or sort-packages
configuration flag to other sections. Find out more about the --sort-packages
flag and configuration at Composer: Config and Composer: Command Line Interface / Commands.
When composer.json
contains version constraints in the
conflict
provide
replace
require
require-dev
sections, the Vendor\Composer\VersionConstraintNormalizer
will ensure that
- all constraints are trimmed
- *and- constraints are separated by a single space (
,
) - *or- constraints are separated by double-pipe with a single space before and after (
||
) - *range- constraints are separated by a single space (
💡 Find out more about version constraints at Composer: Version and Constraints.
Please have a look at CHANGELOG.md
.
Please have a look at CONTRIBUTING.md
.
Please have a look at CODE_OF_CONDUCT.md
.
This package is licensed using the MIT License.
Please have a look at LICENSE.md
.
The algorithm for sorting packages in the Vendor\Composer\PackageHashNormalizer
has been adopted from Composer\Json\JsonManipulator::sortPackages()
(originally licensed under MIT by Nils Adermann and Jordi Boggiano), which I initially contributed to composer/composer
with composer/composer#3549
and composer/composer#3872
.
📬 Subscribe to my list, and I will occasionally send you an email to let you know what I am working on.