Helper Objects#
The helper objects allow you control how specific values are rendered.
They are also designed to be JSON-transparent so you can get an equivalent JSON file by using json_encode()
.
This compatibility may be broken by some planned objects.
Scalar Decorators#
HexInteger
#
Added in version 1.1: $padding
Renders an integer in a hexadecimal form:
<?php
use Arokettu\Json5\Json5Encoder;
use Arokettu\Json5\JsonEncoder;
use Arokettu\Json5\Values\HexInteger;
$value = [
'hex1' => new HexInteger(0xdeadbeef),
'hex2' => new HexInteger(0xbeef),
'hex3' => new HexInteger(0xbeef, 8), // optional padding
];
echo Json5Encoder::encode($value);
echo JsonEncoder::encode($value);
echo json_encode($value, JSON_PRETTY_PRINT);
{
hex1: 0xDEADBEEF,
hex2: 0xBEEF,
hex3: 0x0000BEEF,
}
{
"hex1": 3735928559,
"hex2": 48879,
"hex3": 48879
}
{
"hex1": 3735928559,
"hex2": 48879,
"hex3": 48879
}
Container Decorators#
For arrays and objects.
ArrayValue
and ObjectValue
#
Added in version 1.1.
\Arokettu\Json5\Values\ArrayValue
\Arokettu\Json5\Values\ObjectValue
These two decorators wrap any iterable
or stdClass
to be forced to render as either a array or an object:
<?php
use Arokettu\Json5\Json5Encoder;
use Arokettu\Json5\JsonEncoder;
use Arokettu\Json5\Values\ArrayValue;
use Arokettu\Json5\Values\ObjectValue;
$generator = (fn () => yield from range(0, 3));
$value = [
'array' => new ArrayValue([1 => 2, 3 => 4]), // no need for consecutive keys
'object' => new ObjectValue([1, 2, 3, 4]), // list becomes object
'iterable' => new ArrayValue($generator()), // try a generator
];
echo Json5Encoder::encode($value);
$value['iterable'] = new ArrayValue($generator()); // can't traverse a generator twice
echo JsonEncoder::encode($value);
$value['iterable'] = new ArrayValue($generator()); // can't traverse a generator twice
echo json_encode($value, JSON_PRETTY_PRINT);
{
array: [
2,
4,
],
object: {
'0': 1,
'1': 2,
'2': 3,
'3': 4,
},
iterable: [
0,
1,
2,
3,
],
}
{
"array": [
2,
4
],
"object": {
"0": 1,
"1": 2,
"2": 3,
"3": 4
},
"iterable": [
0,
1,
2,
3
]
}
{
"array": [
2,
4
],
"object": {
"0": 1,
"1": 2,
"2": 3,
"3": 4
},
"iterable": [
0,
1,
2,
3
]
}
Note
If an iterable wrapped by an instance of ObjectValue
(and similar object wrappers) has duplicate keys,
your JSON5 file will have duplicate keys too.
InlineArray
and InlineObject
#
\Arokettu\Json5\Values\InlineArray
\Arokettu\Json5\Values\InlineObject
These wrappers act similar to ArrayValue
and ObjectValue
but intended for small arrays and objects
that can be written in a single line:
<?php
use Arokettu\Json5\Json5Encoder;
use Arokettu\Json5\JsonEncoder;
use Arokettu\Json5\Values\InlineArray;
use Arokettu\Json5\Values\InlineObject;
$value = [
'tinyArray' => new InlineArray([1, 2, 3, 4]),
'tinyObject' => new InlineObject(['key' => 'value']),
];
echo Json5Encoder::encode($value);
echo JsonEncoder::encode($value);
echo json_encode($value, JSON_PRETTY_PRINT);
// Compact and nice
{
tinyArray: [1, 2, 3, 4],
tinyObject: { key: "value" },
}
// Compact and nice too
{
"tinyArray": [1, 2, 3, 4],
"tinyObject": { "key": "value" }
}
// Quite wasteful
{
"tinyArray": [
1,
2,
3,
4
],
"tinyObject": {
"key": "value"
}
}
Nesting container structures is also fine:
<?php
use Arokettu\Json5\Json5Encoder;
use Arokettu\Json5\JsonEncoder;
use Arokettu\Json5\Values\InlineArray;
use Arokettu\Json5\Values\InlineObject;
$value = [
'authors' => new InlineArray([
['name' => 'Andy Gutmans', 'email' => '[email protected]', 'role' => 'co-founder'],
['name' => 'Zeev Suraski', 'email' => '[email protected]', 'role' => 'co-founder'],
]),
'repositories' => [
new InlineObject(['type' => 'vcs', 'url' => 'http://localhost/php.git']),
new InlineObject(['type' => 'vcs', 'url' => 'http://localhost/zend.git']),
],
];
echo Json5Encoder::encode($value);
echo JsonEncoder::encode($value);
echo json_encode($value, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);
{
authors: [{
name: "Andy Gutmans",
email: "[email protected]",
role: "co-founder",
}, {
name: "Zeev Suraski",
email: "[email protected]",
role: "co-founder",
}],
repositories: [
{ type: "vcs", url: "http://localhost/php.git" },
{ type: "vcs", url: "http://localhost/zend.git" },
],
}
{
"authors": [{
"name": "Andy Gutmans",
"email": "[email protected]",
"role": "co-founder"
}, {
"name": "Zeev Suraski",
"email": "[email protected]",
"role": "co-founder"
}],
"repositories": [
{ "type": "vcs", "url": "http://localhost/php.git" },
{ "type": "vcs", "url": "http://localhost/zend.git" }
]
}
{
"authors": [
{
"name": "Andy Gutmans",
"email": "[email protected]",
"role": "co-founder"
},
{
"name": "Zeev Suraski",
"email": "[email protected]",
"role": "co-founder"
}
],
"repositories": [
{
"type": "vcs",
"url": "http://localhost/php.git"
},
{
"type": "vcs",
"url": "http://localhost/zend.git"
}
]
}
CompactArray
and CompactObject
#
\Arokettu\Json5\Values\CompactArray
\Arokettu\Json5\Values\CompactObject
A middle ground between normal and inline structures best used with a manual newline using EndOfLine, also notice various comment types behavior:
<?php
use Arokettu\Json5\Json5Encoder;
use Arokettu\Json5\JsonEncoder;
use Arokettu\Json5\Values\Comment;
use Arokettu\Json5\Values\CommentDecorator;
use Arokettu\Json5\Values\CompactArray;
use Arokettu\Json5\Values\CompactObject;
use Arokettu\Json5\Values\EndOfLine;
$value = [
'tinyArray' => new CompactArray([1, 2, new EndOfLine(), 3, 4]),
'tinyObject' => new CompactObject(['key1' => 'value1', 'key2' => 'value2']),
'comments' => new CompactArray([
new Comment('Standalone comment is a line comment'),
new CommentDecorator('become', 'Decorator comments', 'inline comments'),
]),
];
echo Json5Encoder::encode($value);
echo JsonEncoder::encode($value);
echo json_encode($value, JSON_PRETTY_PRINT);
{
tinyArray: [
1, 2,
3, 4,
],
tinyObject: {
key1: "value1", key2: "value2",
},
comments: [
// Standalone comment is a line comment
/* Decorator comments */ "become" /* inline comments */,
],
}
{
"tinyArray": [
1, 2,
3, 4
],
"tinyObject": {
"key1": "value1", "key2": "value2"
},
"comments": [
"become"
]
}
{
"tinyArray": [
1,
2,
{},
3,
4
],
"tinyObject": {
"key1": "value1",
"key2": "value2"
},
"comments": [
{
"comment": "Standalone comment is a line comment"
},
"become"
]
}
Common Decorators#
CommentDecorator
#
Renders a value with comments. The commentBefore
may be multiline, the commentAfter
must be a single line:
<?php
use Arokettu\Json5\Json5Encoder;
use Arokettu\Json5\JsonEncoder;
use Arokettu\Json5\Values\CommentDecorator;
$value = new CommentDecorator([ // root level supported too
'g' => new CommentDecorator(6.6743e-11, commentBefore: <<<TEXT
This is the Gravitational constant
Changing it may collapse the Universe
TEXT, commentAfter: 'Universe is safe'),
], commentBefore: 'This time this comment is really rendered by the lib');
echo Json5Encoder::encode($value);
echo JsonEncoder::encode($value);
echo json_encode($value, JSON_PRETTY_PRINT);
// This time this comment is really rendered by the lib
{
// This is the Gravitational constant
// Changing it may collapse the Universe
g: 6.6743e-11, // Universe is safe
}
{
"g": 6.6743e-11
}
{
"g": 6.6743e-11
}
Comments will be rendered as inline comments in compact and inline modes:
<?php
use Arokettu\Json5\Json5Encoder;
use Arokettu\Json5\JsonEncoder;
use Arokettu\Json5\Values\CommentDecorator;
use Arokettu\Json5\Values\InlineArray;
$value = new InlineArray([
new CommentDecorator('value', 'inline before', 'inline after'),
]);
echo Json5Encoder::encode($value);
echo JsonEncoder::encode($value);
echo json_encode($value, JSON_PRETTY_PRINT);
[/* inline before */ "value" /* inline after */]
["value"]
[
"value"
]
Interfaces#
JsonSerializable
#
ext-json
’s JsonSerializable
works with this builder just like it works with json_encode
.
Json5Serializable
#
\Arokettu\Json5\Values\Json5Serializable
.
Like JsonSerializable
but it’s specific to this library.
Formatting Objects#
Note
Formatting Objects are not transparent for the json_encode
and will be encoded as regular objects, see examples.
Note
Formatting Objects cannot be encoded as root objects and cannot be returned in json5Serialize()
and jsonSerialize()
methods.
Comment
#
\Arokettu\Json5\Values\Comment
A standalone comment. Rendered as a line comment in regular and compact modes and as an inline comment in inline mode:
<?php
use Arokettu\Json5\Json5Encoder;
use Arokettu\Json5\JsonEncoder;
use Arokettu\Json5\Values\Comment;
use Arokettu\Json5\Values\CompactArray;
use Arokettu\Json5\Values\InlineArray;
require __DIR__ . '/../vendor/autoload.php';
$value = [
'normal' => [new Comment('Normal mode'), 'value1', 'value2', 'value3'],
'compact' => new CompactArray([
new Comment('Unlike decorator, standalone comment is rendered on its own line here'),
'value1',
'value2',
new Comment('JsonEncoder will leave EOL here'),
'value3',
]),
'inline' => new InlineArray([new Comment('Inline mode'), 'value1', 'value2', 'value3']),
];
echo Json5Encoder::encode($value);
echo JsonEncoder::encode($value);
echo json_encode($value, JSON_PRETTY_PRINT);
{
normal: [
// Normal mode
"value1",
"value2",
"value3",
],
compact: [
// Unlike decorator, standalone comment is rendered on its own line here
"value1", "value2",
// JsonEncoder will leave EOL here
"value3",
],
inline: [/* Inline mode */ "value1", "value2", "value3"],
}
{
"normal": [
"value1",
"value2",
"value3"
],
"compact": [
"value1", "value2",
"value3"
],
"inline": ["value1", "value2", "value3"]
}
{
"normal": [
{
"comment": "Normal mode"
},
"value1",
"value2",
"value3"
],
"compact": [
{
"comment": "Unlike decorator, standalone comment is rendered on its own line here"
},
"value1",
"value2",
{
"comment": "JsonEncoder will leave EOL here"
},
"value3"
],
"inline": [
{
"comment": "Inline mode"
},
"value1",
"value2",
"value3"
]
}
EndOfLine
#
\Arokettu\Json5\Values\EndOfLine
Inserts a newline character:
<?php
use Arokettu\Json5\Json5Encoder;
use Arokettu\Json5\JsonEncoder;
use Arokettu\Json5\Values\CompactArray;
use Arokettu\Json5\Values\EndOfLine;
use Arokettu\Json5\Values\InlineArray;
$value = [
'regular' => [1, 2, new EndOfLine(), 3, 4],
'inline' => new InlineArray([1, 2, new EndOfLine(), 3, 4]),
'compact' => new CompactArray([1, 2, new EndOfLine(), 3, 4]),
];
echo Json5Encoder::encode($value);
echo JsonEncoder::encode($value);
echo json_encode($value, JSON_PRETTY_PRINT);
{
regular: [
1,
2,
3,
4,
],
inline: [1, 2,
3, 4],
compact: [
1, 2,
3, 4,
],
}
{
"regular": [
1,
2,
3,
4
],
"inline": [1, 2,
3, 4],
"compact": [
1, 2,
3, 4
]
}
{
"regular": [
1,
2,
{}, // not transparent
3,
4
],
"inline": [
1,
2,
{}, // not transparent
3,
4
],
"compact": [
1,
2,
{}, // not transparent
3,
4
]
}