README

Laravel Toon Converter (json to toon for LLMs)

Laravel integration for TOON format: encode/decode JSON data into a token‑optimized notation for LLMs. This package provides first‑class TOON support in Laravel with spec‑conformant encoding/decoding, smart tabular formatting, safe key folding, and developer‑friendly APIs (Facade, helpers, DI).

Requirements

PHP >= 8.0.1
Laravel >= 9.19
Composer

Installation

Install via Composer:

composer require jobmetric/laravel-toon

The service provider is auto‑discovered. The Toon facade and global helpers are registered.

Configuration

Publish/override the laravel-toon config as needed. Available options (defaults in parentheses):

indent (2): spaces per indent level (encoder/decoder)
delimiter (','): array delimiter — one of ,, \t, |
- Non‑default delimiter appears in headers, e.g. [3|]: 1|2|3 or [2\t]{id\tname}:
min_rows_tabular (1): if list of uniform objects has ≥ this count, use tabular format
newline_final (false): append trailing newline on encode
key_folding ('off'): 'off' or 'safe' — fold single‑key chains into dotted path when safe
flatten_depth (-1): max depth of folding (-1 = unlimited)
folding_exclude ([]): prefixes to opt‑out from folding
expand_paths (false): expand dotted keys on decode (safe segments only)
throw_on_decode_error (true): throw on invalid TOON; otherwise return null
numbers_as_strings (false): decode numbers as strings instead of numeric types
spec_strict (true): prefer strict spec behavior (no trailing newline, stricter normalization)

Features

Spec‑Conformant Headers
- Primitive arrays: [n]: v1,v2,v3
- Tabular arrays: [n]{k1,k2}: then rows indented one level
- Delimiter suffix for non‑default delimiters in headers: [n|], [n\t]
- Empty arrays: [0]:
Smart Tabular Encoding
- Detects uniform lists of objects; emits compact tabular blocks with header fields
- Human‑readable and token‑efficient (ideal for LLM prompts)
Mixed Arrays with Nested Items
- Renders [n]: then list items with - , and handles nested multi‑line blocks with correct indentation
Safe Key Folding (optional)
- key_folding='safe' flattens chains of single‑key nested objects into dot paths when safe; flatten_depth and folding_exclude supported
Safe Path Expansion (optional)
- expand_paths=true expands dotted keys into nested objects on decode (safe segments only)
Robust Decoding and Validation
- Strict indentation checks; array length and tabular row count validation
- Configurable error handling via throw_on_decode_error
Predictable String/Numeric Handling
- Spec‑style quoting/escaping; optional numbers_as_strings mode
First‑Class Laravel Integration
- Facade Toon::encode / Toon::decode
- Global helpers toon_encode / toon_decode
- Container singleton and alias 'Toon' for DI

Usage

Facade

use JobMetric\Toon\Facades\Toon;

$data = [
    'id' => 42,
    'tags' => ['x', 'y'],
    'users' => [
        ['id' => 1, 'name' => 'Alice'],
        ['id' => 2, 'name' => 'Bob'],
    ],
];

$toon = Toon::encode($data);
// [2]{id,name}:
//   1,Alice
//   2,Bob

$decoded = Toon::decode($toon);
// same as $data

Helpers

$encoded = toon_encode(['numbers' => [1, 2, 3]]);
// [3]: 1,2,3

$decoded = toon_decode($encoded);

Container/DI

use JobMetric\Toon\ToonManager;

$toon = app(ToonManager::class)->encode(['items' => ['a', 'b']]);
// items[2]: a,b

Custom Delimiter

config()->set('laravel-toon.delimiter', '|');

echo Toon::encode(['nums' => [1,2,3]]);
// nums[3|]: 1|2|3

Safe Key Folding + Path Expansion

config()->set('laravel-toon.key_folding', 'safe');
config()->set('laravel-toon.expand_paths', true);

$encoded = Toon::encode(['a' => ['b' => ['c' => 1]]]);
// a.b.c: 1
$decoded = Toon::decode($encoded);
// ['a' => ['b' => ['c' => 1]]]

Error Handling

config()->set('laravel-toon.throw_on_decode_error', false);
$decoded = toon_decode("id:\n   name: Alice\n"); // null (no exception)

Numbers as Strings

config()->set('laravel-toon.numbers_as_strings', true);

$decoded = Toon::decode('n: 12345678901234567890');
// ['n' => '12345678901234567890']

Spec Notes (Parity)

Headers only include delimiter suffix when non‑default (, is implicit): [3|], [2\t].
Tabular header fields are delimited using the same active delimiter.
Strings are quoted only when necessary (whitespace, delimiter present, structural chars, looks like literal/number, control chars, backslash).
Keys are unquoted when safe; dotted keys allowed when each segment is a safe identifier.
Decoder enforces indentation width to be multiples of indent (default 2).

Why jobmetric/laravel-toon

Spec‑accurate TOON for Laravel (delimiter‑aware headers, robust parsing)
Token‑efficient formatting — especially tabular encoding
Safety controls (folding/expand for safe identifiers, strict indentation)
Predictable numeric/string handling (optional strings for large numbers)
Developer experience: Facade, helpers, alias, simple config

Contributing

Thank you for considering contributing to Laravel Toon! Please see CONTRIBUTING.md.

License

The MIT License (MIT). See LICENCE.md for details.

jobmetric / laravel-toon

Maintainers

Details