json-normalizer
Provides generic and vendor-specific normalizers for normalizing JSON documents.
Installation
Run
$ composer require ergebnis/json-normalizer
Usage
Generic normalizers
This package comes with the following generic normalizers:
Ergebnis\Json\Normalizer\AutoFormatNormalizerErgebnis\Json\Normalizer\CallableNormalizerErgebnis\Json\Normalizer\ChainNormalizerErgebnis\Json\Normalizer\FixedFormatNormalizerErgebnis\Json\Normalizer\IndentNormalizerErgebnis\Json\Normalizer\JsonEncodeNormalizerErgebnis\Json\Normalizer\SchemaNormalizerErgebnis\Json\Normalizer\WithFinalNewLineNormalizerErgebnis\Json\Normalizer\WithoutFinalNewLineNormalizer
Ergebnis\Json\Normalizer\NormalizerInterface.
AutoFormatNormalizer
When you want to normalize a JSON file with an implementation of NormalizerInterface, but retain the original formatting, you can use the AutoFormatNormalizer.
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\Normalizer $composedNormalizer */
$normalizer = new Normalizer\AutoFormatNormalizer(
$composedNormalizer,
new Normalizer\Format\DefaultFormatter(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
FixedFormatNormalizer.
CallableNormalizer
When you want to normalize a JSON file with a callable, you can use the CallableNormalizer.
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.
ChainNormalizer
When you want to apply multiple normalizers in a chain, you can use the ChainNormalizer.
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.
FixedFormatNormalizer
When you want to normalize a JSON file with an implementation of NormalizerInterface, but apply a fixed formatting, you can use the FixedFormatNormalizer.
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\Normalizer $composedNormalizer */
/* @var Normalizer\Format\Format $format */
$normalizer = new Normalizer\FixedFormatNormalizer(
$composedNormalizer,
$format,
new Normalizer\Format\DefaultFormatter(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.
AutoFormatNormalizer.
IndentNormalizer
When you need to adjust the indentation of a JSON file, you can use the IndentNormalizer.
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.
JsonEncodeNormalizer
When you need to adjust the encoding of a JSON file, you can use the JsonEncodeNormalizer.
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.
json_encode() and the corresponding JSON constants.
SchemaNormalizer
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.
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.
WithFinalNewLineNormalizer
When you want to ensure that a JSON file has a single final new line, you can use the WithFinalNewLineNormalizer.
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.
WithoutFinalNewLineNormalizer
When you want to ensure that a JSON file does not have a final new line, you can use the WithoutFinalNewLineNormalizer.
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.
Vendor-specific normalizers
This package comes with the following vendor-specific normalizers:
Vendor\Composer\ComposerJsonNormalizer
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\BinNormalizerErgebnis\Composer\Json\Normalizer\Vendor\Composer\ConfigHashNormalizerErgebnis\Composer\Json\Normalizer\Vendor\Composer\PackageHashNormalizerErgebnis\Composer\Json\Normalizer\Vendor\Composer\VersionConstraintNormalizer
Vendor\Composer\BinNormalizer
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.
bin section at Composer: The composer.json schema.
Vendor\Composer\ConfigHashNormalizer
When composer.json contains any configuration in the
configextrascripts-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.
config section at Composer: The composer.json schema.
Vendor\Composer\PackageHashNormalizer
When composer.json contains any configuration in the
conflictprovidereplacerequirerequire-devsuggest
sections, the Vendor\Composer\PackageHashNormalizer will sort the content of these sections.
--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.
Vendor\Composer\VersionConstraintNormalizer
When composer.json contains version constraints in the
conflictprovidereplacerequirerequire-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 (
Changelog
Please have a look at CHANGELOG.md.
Contributing
Please have a look at CONTRIBUTING.md.
Code of Conduct
Please have a look at CODE_OF_CONDUCT.md.
License
This package is licensed using the MIT License.
Please have a look at LICENSE.md.
Credits
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.
Curious what I am building?
4 Jul 2, 2022
311 Nov 20, 2022
15 Dec 16, 2022
133 Oct 26, 2022
24 Oct 13, 2022
195 Dec 24, 2022
1.2k Jan 2, 2023
3 Sep 5, 2022
127 Dec 17, 2022
136 Dec 30, 2022
13 Oct 4, 2022
14 Oct 18, 2022
21 Oct 21, 2021
7 Jul 19, 2021
0 Jul 28, 2022
0 Oct 22, 2021
0 Nov 6, 2022
7 Dec 21, 2022
92 Dec 7, 2022