mischasigtermans/laravel-toon v2.0.0

on PHP Packagist

Targets the TOON v4.1 specification. Nested objects stay in tables through nested field groups, and objects of uniform objects get a keyed table form. Encoder and decoder are rewritten against the spec and pass all 538 official fixtures.

Upgrading from 1.x

• If you only encode for an LLM, update a published config (Migration step 1) and you're done.
• If you decode this package's output elsewhere, or store it, upgrade those decoders first and re-encode stored TOON (steps 4 and 5).
• If you construct ToonEncoder or ToonDecoder yourself, or call ArrayFlattener or ArrayUnflattener, see steps 2 and 3.

Breaking

• Nested objects in tabular arrays encode as nested field groups ({id,artist{id,name}}) instead of dot-notation columns ({id,artist.id,artist.name}). The decoder reads dotted field names as literal keys.
• Arrays whose nested objects differ in shape use list form instead of a padded table with null cells.
• Objects whose values are two or more uniform objects encode in keyed tabular form (servers[2:]{host,port}:).
• Empty arrays encode as key: [] and root [] instead of key[0]:.
• Strings starting with # or containing [, ] anywhere are quoted.
• Empty tabular cells decode to "" instead of null.
• The decoder drops legacy backslash unescaping (Hello\, World). Unquoted tokens decode as-is.
• Invalid escape sequences, unterminated strings and bare scalar lines error in non-strict mode too.
• Requires Laravel 12 or 13. Every Laravel 10 and 11 release carries unpatched security advisories, and Composer refuses to install them by default. Stay on 1.x for those versions.
• number_precision rounds to canonical form: 99.5, not 99.50, and 100, not 100.00.
• min_rows_for_table defaults to 1. The spec requires tabular form for every uniform array.
• ToonEncoder and ToonDecoder take the config array as their only constructor argument.
• toon_decode() returns mixed, so a root primitive comes back as itself.
• Removed the key_folding, key_folding_depth and expand_paths config options, following their removal from the spec.
• Removed the max_flatten_depth config option. Nested field groups have no depth limit.
• Removed the ArrayFlattener and ArrayUnflattener support classes.

Added

• Keyed tabular form for objects of uniform objects, encode and decode.
• Nested field groups at any depth, encode and decode.
• Full-line # comments are skipped when decoding.
• \uXXXX escapes for control characters.
• Strict-mode errors for malformed headers, duplicate keys, indentation jumps and trailing content after a root array.
• BackedEnum, JsonSerializable and Stringable values are normalized before encoding.

Fixed

• Keys containing . inside nested objects no longer break tabular encoding (#13).
• truncate_strings counts characters, so a cut never splits a multibyte character.

Migration

1. Remove max_flatten_depth, key_folding, key_folding_depth and expand_paths from a published config/toon.php, and set min_rows_for_table to 1.
2. Pass the config as the first constructor argument: new ToonEncoder($config). A 1.x call, new ToonEncoder(null, $config), still runs on 2.0 and ignores $config.
3. ArrayFlattener and ArrayUnflattener have no replacement. The encoder and decoder handle nesting themselves.
4. Re-encode stored TOON that used dot-notation columns, key folding or 0.x backslash escaping: decode it with 1.x, encode it with 2.0.
5. Update decoders that read this package's output before upgrading the encoder. A 1.x decoder misreads nested field groups, keyed tables and empty arrays without an error: tags: [] comes back as the string "[]".