README

Compact, human-readable, and token-efficient structured data for AI prompts, logs, and Laravel workflows

What This Package Is

TOON is a Laravel package for converting JSON or PHP arrays into a compact text format that stays readable to humans and efficient for AI-oriented workflows.

It is useful when JSON is too noisy for:

ChatGPT, Gemini, Claude, Mistral, and OpenAI prompt payloads
log snapshots and debug output
internal structured storage or fixture review
repeated API resource collections with the same fields

Why TOON Helps

JSON repeats a lot of structure. TOON removes much of that repetition while keeping the data understandable.

Example input:

$payload = [
    'project' => 'TOON',
    'users' => [
        ['id' => 1, 'name' => 'Alice', 'active' => true],
        ['id' => 2, 'name' => 'Bob', 'active' => false],
    ],
];

Example TOON output:

project: TOON
users:
  items[2]{id,name,active}:
    1,Alice,true
    2,Bob,false

Core Features

Install in 60 Seconds

composer require sbsaga/toon

Optional config publishing:

php artisan vendor:publish --provider="Sbsaga\Toon\ToonServiceProvider" --tag=config

How It Works

Laravel Usage

Facade usage:

use Sbsaga\Toon\Facades\Toon;

$toon = Toon::encode($payload);
$decoded = Toon::decode($toon);
$stats = Toon::estimateTokens($toon);
$diff = Toon::diff($payload);

Replacer usage:

use Sbsaga\Toon\Facades\Toon;

$toon = Toon::encodeWith($payload, function (array $path, string|int|null $key, mixed $value) {
    if ($key === 'debug') {
        return Toon::skip();
    }

    if ($key === 'email') {
        return '[redacted]';
    }

    return $value;
});

Global helpers:

$toon = toon_encode($payload);
$toonFiltered = toon_encode_with($payload, fn (array $path, string|int|null $key, mixed $value) => $value);
$decoded = toon_decode($toon);
$diff = toon_diff($payload);

Collection macro:

$toonRows = collect($payload['users'])->toToon();

Streaming convenience:

$lines = Toon::encodeLines($payload); // Generator<string>
$decoded = Toon::decodeFromLines($lines);

CLI conversion (advanced options):

php artisan toon:convert storage/example.json --from=json --to=toon --stats
php artisan toon:convert storage/example.toon --decode --strict --pretty
php artisan toon:convert storage/example.json --mode=modern --delimiter=pipe --output=storage/example.toon

Laravel Integration Architecture

Backward Compatibility First

This release keeps legacy compatibility mode as the default so existing projects are less likely to break after upgrade.

Default stable API:

Toon::convert()
Toon::encode()
Toon::decode()
Toon::estimateTokens()

New optional improvements:

Toon::diff()
Toon::convertWith()
Toon::encodeWith()
Toon::skip()
Toon::encodeLines()
Toon::decodeFromLines()
Toon::promptBlock()
Toon::validate()
Toon::contentType()
Toon::fileExtension()
toon_encode()
toon_encode_with()
toon_encode_lines()
toon_decode()
toon_diff()
toon_prompt()
toon_validate()
Collection::toToon()
Sbsaga\Toon\Concerns\Toonable
strict_mode
delimiter
compatibility_mode

If you want safer nested round trips and cleaner decode behavior for new work, opt into modern mode:

// config/toon.php
'compatibility_mode' => 'modern',

Reproducible Benchmark

The repository includes a synthetic benchmark fixture and runner:

Run it locally:

php benchmarks/run.php benchmarks/fixtures/paginated-users.json

Current result for the included synthetic fixture:

Metric	JSON	TOON
Characters	2622	1492
Estimated comparison tokens	656	373
Character savings		43.1%

Notes:

the fixture data is synthetic and repository-generated
the token comparison is a lightweight heuristic for relative comparison
repeated scalar rows usually benefit most from TOON tables

Why Trust This Package

Laravel-native facade, service provider, helpers, and collection macro
backward-safe default compatibility mode for existing users
opt-in modern mode for cleaner nested-data behavior
delimiter and strict parsing controls for production use
benchmark fixture and docs included in the repo
test coverage for encoder, decoder, helpers, macros, compatibility modes, and edge cases

Documentation

New here: start with Quickstart, then Cookbook: real-world examples.

Shipping to production: read Production playbook, then Migration guide, and keep Troubleshooting handy.

sbsaga / toon

Maintainers

Package info

Statistics

Security