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

Install in 60 Seconds

composer require sbsaga/toon

Optional config publishing:

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

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);

Global helpers:

$toon = toon_encode($payload);
$decoded = toon_decode($toon);
$diff = toon_diff($payload);

Collection macro:

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

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::promptBlock()
Toon::validate()
Toon::contentType()
Toon::fileExtension()
toon_encode()
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

sbsaga / toon

Maintainers

Package info

Statistics

Security

README

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

What This Package Is

Why TOON Helps

Install in 60 Seconds

Laravel Usage

Backward Compatibility First

Reproducible Benchmark

Why Trust This Package

Documentation

More README Files

Example Packages and Scenarios

Branding Asset

License