NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
Packagist
Packagist, #2037 most downloaded on Packagist
Token-Oriented Object Notation - A compact data format for reducing token consumption when sending structured data to LLMs
Latest stable
v3.3.0
Last release 16 days ago
06 Nov 2026
Release timing varies
gaps range from 9 days to 7 months
Nearly every release is documented
notes for 11 of 11 stable releases
Nothing withdrawn
no release was ever pulled
1 years old
11 releases · first in 2025
Drag across the ruler to compare, or tap a release to open it.
Package 3.3.0 adds explicit TOON wire-format selection while keeping existing calls compatible with release 3.2.1.
Package 3.3.0 adds explicit TOON wire-format selection while keeping existing calls compatible with release 3.2.1.
use HelgeSverre\Toon\EncodeOptions;
use HelgeSverre\Toon\DecodeOptions;
use HelgeSverre\Toon\SpecVersion;
use HelgeSverre\Toon\Toon;
$wire = Toon::encode($data, new EncodeOptions(version: SpecVersion::V4_4));
$data = Toon::decode($wire, new DecodeOptions(version: SpecVersion::V4_4));
^3.2.1 consumer constraint. Mate's encoding/command tests, response probe and a real project-defined tool all passed, with byte-identical output to 3.2.1. Both opt-in codecs also passed extension-free smoke checks against the published distribution on PHP 8.1–8.5.Objects continue decoding to associative arrays; empty-object/list and sequential numeric-key distinctions may be lost after decoding. The default profile retains its documented legacy deviations.
Thanks to @voku for #6 and @zip-fa for #8 and #9. Their format work was adapted into the versioned codec architecture.
See version selection and compatibility, release validation, and the changelog.
Downstream comparison evidence includes synthetic response probes, real project tool outputs and the full Mate baseline/candidate logs. Its provenance file explains the existing standalone bridge-reference failures.
Your coding agent can read these notes before it upgrades. Set up the MCP server →
SpecVersion, EncodeOptions, DecodeOptions, and withVersion(). Omitted versions retain release 3.2.1 behavior; there is no detection, fallback, or global version setting.serialize_precision setting, restoring it after conversion.unescaped-char: supplementary scalars (%x10000-10FFFF) included explicitly.n = 0 or 1e-6 ≤ |n| < 1e21; outside this range, encoders MAY emit exponent notation per the JSON number grammar (lowercase e, explicit sign recommended).json.Marshaler), Python (JSONEncoder.default), Rust (serde::Serialize); host hooks take precedence over default mappings.indent → indentSize for consistency with §1.3 / §12.Patch release fixing a decoder round-trip regression introduced in v3.2.0.
Patch release fixing a decoder round-trip regression introduced in v3.2.0.
[ or { — for example k: "a[3]b", or log lines carrying ANSI escape sequences such as "[31m…" — were misread as array headers and raised SyntaxException: Unterminated quoted string on decode, so the encoder's own output could not be decoded back. Header detection now locates the : separator and the [/{ markers outside quoted spans, so encoder output round-trips through Toon::decode() for every string value. The regression was introduced in v3.2.0; v3.1.0 was unaffected.tests/Spec/RoundTripSpecialStringsTest.php, tests/Spec/ComprehensiveRoundTripTest.php, tests/Spec/MalformedHeaderDecodeTest.php); line coverage raised from 90% to 96%.DelimiterParser helpers) with no change to the public decode path.Full Changelog: https://github.com/HelgeSverre/toon-php/compare/v3.2.0...v3.2.1
[ or { — for example k: "a[3]b", or log lines carrying ANSI escape sequences such as "[31m…" — were misread as array headers and raised SyntaxException: Unterminated quoted string on decode. Header detection now locates the : separator and the [/{ markers outside quoted spans, so encoder output round-trips through Toon::decode() for every string value. Regression introduced in v3.2.0 (v3.1.0 was unaffected). Added comprehensive bidirectional round-trip test coverage (tests/Spec/RoundTripSpecialStringsTest.php, tests/Spec/ComprehensiveRoundTripTest.php).This release brings the library into conformance with TOON Specification v3.3 (upstream advanced v3.0 → v3.3) and adds a validation API.
This release brings the library into conformance with TOON Specification v3.3 (upstream advanced v3.0 → v3.3) and adds a validation API.
docs/SPEC.md and docs/CHANGELOG.md.\n, \r, \t) as \uXXXX; the decoder accepts \uXXXX (case-insensitive hex) and rejects lone surrogates and escapes with fewer than four hex digits.[] and key: [] forms in addition to the legacy [0]: / key[0]: forms.Toon::validate(), toon_validate() and toon_validate_lenient() for checking TOON syntax without decoding.tests/Spec/Version31To33ComplianceTest.php.n = 0 or 1e-6 ≤ |n| < 1e21; values outside that range use exponent notation (lowercase e, explicit sign, e.g. 1e+21, 1e-7). Large in-domain floats are no longer quoted as strings, and very small numbers no longer underflow to 0.[03] (§6, §14.2), header delimiter mismatches where the bracket delimiter differs from the field-list delimiter, e.g. rows[2|]{a,b}: (§6, §14.2), and duplicate sibling keys at the same depth (§8, §14.4). Non-strict mode treats malformed bracket tokens as literal keys and applies last-write-wins for duplicate keys."App\Controller::method") now decode correctly (#4, #5).key: [] previously decoded to null and a bare [] crashed with an uninitialized-offset warning; both now decode to an empty array.- [M]: … → inner array, - key: … → object, bare - → empty object. This fixes round-trips for arrays of arrays and lists of single-field objects.null (lenient).key: (§8): decodes to an empty object, not null."my-key"[3]: is unescaped.[3]: a,,b → ['a','','b'])."a\\": c) parses.EncodeOptions/DecodeOptions reject indent < 1; EncodeOptions::compact() now uses indent: 1 so nested output round-trips.Toon::validate() now runs the full decoder internally and returns false only when decode() throws, so validation and decoding can never disagree. The separate validator implementation was removed.Full Changelog: https://github.com/HelgeSverre/toon-php/compare/v3.1.0...v3.2.0
- [M<delim?>]: followed by items at depth +1 relative to the hyphen line; tabular form is unavailable in this position, encoders MUST use the expanded list form).[03]), and any content between the bracket segment, optional fields segment, and colon. Non-strict mode MAY fall through to key-value parsing.{} MUST NOT use tabular form (encoded via §9.4 expanded list instead).unescaped-char extended to include U+0009 (HTAB), expressing decoder leniency only; encoders MUST emit \t per the escape table.\uXXXX escapes are not combined.quoted-key (§6), quoted-char, and unescaped-char (§7.1) productions; literal codepoints in quoted keys were ungrammatical under the prior *escaped-char rule."x-items"[2]: example reshaped to non-uniform objects (previous example violated §9.3).toJSON() support: Objects with a toJSON() method can now provide custom serialization, similar to JSON.stringify in JavaScript
toJSON() method can now provide custom serialization, similar to JSON.stringify in JavaScript-05, -0001) as strings per spec §2.4toJSON() method can now provide custom serialization, similar to JSON.stringify in JavaScript. The method takes priority over JsonSerializable interface and includes recursion protectiontests/Spec/Version3BreakingChangesTest.php with 6 tests verifying v3.0 compliancetest_tabular_first_field_in_list_item_round_trip to verify v3.0 format survives encode/decode cycles-05, -0001) as strings per TOON Specification §2.4\uXXXX Unicode escape in quoted strings and keys; encoders MUST emit it for control characters U+0000–U+001F outside \n, \r, \t (§7.1).key: [] for object-field position and [] for root position (§9.1, §5). Decoders MUST accept both canonical (key: [], []) and legacy (key[0]:, [0]:) forms.This major release aligns with TOON Specification v3.0, which standardizes the encoding for list-item objects whose first field is a tabular array.
This major release aligns with TOON Specification v3.0, which standardizes the encoding for list-item objects whose first field is a tabular array.
When a list-item object has a tabular array as its first field:
Before (v2.x):
items[1]:
- users[2]{id,name}:
1,Ada
2,Bob
status: active
After (v3.0):
items[1]:
- users[2]{id,name}:
1,Ada
2,Bob
status: active
tests/Spec/Version3BreakingChangesTest.php with 6 tests verifying v3.0 compliance- key[N]{fields}: on the hyphen line.Added 10 tests for v2.0 breaking change verification
This major release aligns with TOON Specification v2.0, which removes the optional # length marker prefix from array headers.
EncodeOptions::$lengthMarker parameter removed from constructorEncodeOptions::withLengthMarkers() preset method removedEncodeOptions::withLengthMarker() fluent setter removed[N] format (e.g., [3]: a,b,c)[#N] format with SyntaxExceptionBefore (v1.x):
$options = EncodeOptions::withLengthMarkers();
$toon = Toon::encode($data, $options);
// Output: [#3]: a,b,c
After (v2.0):
$options = EncodeOptions::default();
$toon = Toon::encode($data, $options);
// Output: [3]: a,b,c
sprintf() calls that caused decimal points to become commas in locales like da_DK, de_DE. Now uses number_format() with explicit decimal separator for locale-independent formatting per TOON Spec §2.InvalidArgumentException. Only \n, \r, and \t have defined escape sequences per TOON Spec §7.1.[N#] now produces correct v2.0 error messagedocs/SPEC-COMPLIANCE.md with control character policy and v2.0 compliance detailsThis major release aligns with TOON Specification v2.0, which removes the optional # length marker prefix from array headers. The library version now matches the spec version for clarity.
EncodeOptions::$lengthMarker parameter - The optional length marker parameter has been removed from the constructorEncodeOptions::withLengthMarkers() preset - This preset method has been removedEncodeOptions::withLengthMarker() method - This fluent setter has been removed[N] format (e.g., [3]: a,b,c). The deprecated [#N] format is no longer supported.[#N] format with SyntaxException. Previously accepted both [N] and [#N] formats.Before (v1.x):
use HelgeSverre\Toon\EncodeOptions;
use HelgeSverre\Toon\Toon;
// Using preset with length markers
$options = EncodeOptions::withLengthMarkers();
$toon = Toon::encode($data, $options);
// Output: [#3]: a,b,c
// Using constructor
$options = new EncodeOptions(lengthMarker: '#');
$toon = Toon::encode($data, $options);
After (v2.0):
use HelgeSverre\Toon\EncodeOptions;
use HelgeSverre\Toon\Toon;
// Use default options (no length marker parameter)
$options = EncodeOptions::default();
$toon = Toon::encode($data, $options);
// Output: [3]: a,b,c
// Constructor no longer accepts lengthMarker
$options = new EncodeOptions();
$toon = Toon::encode($data, $options);
[#N] format[N] format[#N] format with clear error messageslengthMarker parameter and related methodsEncodeOptions::$lengthMarker propertyEncodeOptions::withLengthMarkers() static methodEncodeOptions::withLengthMarker() instance methodsprintf() calls that were locale-dependent, causing decimal points to become commas in locales like da_DK, de_DE, etc. Now uses number_format() with explicit decimal point separator for guaranteed locale-independent formatting per TOON Spec §2. This ensures output is always valid regardless of system locale settings.InvalidArgumentException. Per TOON Spec §7.1, only \n, \r, and \t have defined escape sequences. This prevents potential security issues from raw control characters in output.[N#] (hash after digits) now produces the correct v2.0 error message instead of a generic errortests/Spec/Version2BreakingChangesTest.php)docs/SPEC-COMPLIANCE.md with control character policy and v2.0 verification details[#N] length-marker syntax in array headers; [N] is now the only valid format.[#N]; decoders MUST reject it.lengthMarker encoder option and any CLI flags exposing it.[#N] syntax..toon files using [#N] to [N].lengthMarker configuration and CLI options.Full TOON decoder implementation: Complete decoding functionality with strict mode support
just benchmark-performance - Run PHPBench with default reportjust benchmark-perf-summary - Run with summary reportjust benchmark-all - Run both token efficiency and performance benchmarksjust benchmark-baseline - Store current performance as baselinejust benchmark-compare - Compare against stored baseline"0"), plus decoder handling of exponent forms and out-of-range numbers (§2–§3).\w with explicit [A-Za-z0-9_] in key regexes for cross-language clarity (§7.3).Native PHP enum support for both BackedEnum and UnitEnum types:
Native PHP enum support for both BackedEnum and UnitEnum types:
Thanks to @AmolKumarGupta for contributing this feature!
BackedEnum and UnitEnum types
Status::ACTIVE → "active")Counting::TWO → "TWO")HttpCode::cases() → "[2]: 201,400")Number.toString() precision (15–17 digits); all implementations MUST preserve round-trip fidelity (§2).Empty array encoding now correctly outputs [0] length marker
[0] length marker
items:items[0]:Full changelog: https://github.com/HelgeSverre/toon-php/blob/main/CHANGELOG.md#120---2025-10-28
[0] length marker (e.g., items[0]:)Justfile for task automation with commands for setup, testing, analysis, formatting, benchmarks, quality checks, and CI workflows
Token savings compared to other formats:
Full changelog: https://github.com/HelgeSverre/toon-php/blob/main/CHANGELOG.md#110---2025-10-28
just commands for:
Toon::encode() methodindent, strict).TOON (Token-Oriented Object Notation) is a compact data format for reducing token consumption when sending structured data to Large Language Models.
TOON (Token-Oriented Object Notation) is a compact data format for reducing token consumption when sending structured data to Large Language Models.
composer require helgesverre/toon
use HelgeSverre\Toon\Toon;
echo Toon::encode([
'items' => [
['sku' => 'A1', 'qty' => 2, 'price' => 9.99],
['sku' => 'B2', 'qty' => 1, 'price' => 14.5]
]
]);
Output:
items[2]{sku,qty,price}:
A1,2,9.99
B2,1,14.5
Full changelog: https://github.com/HelgeSverre/toon-php/commits/v1.0.0
Toon::encode() static methodEncodeOptions:
EncodeOptions with fluent APIOne column per month.