sbsaga/toon

TOON for Laravel

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:

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

Run it locally:

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

Current result for the included synthetic fixture:

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.

• Docs index
• Quickstart
• Cookbook: real-world examples
• Production playbook
• Upgrade safety for v1.3.0
• CLI conversion guide
• Replacer recipes
• Format and compatibility
• Syntax cheatsheet
• LLM integration guide
• Media type and files
• When not to use TOON
• Migration guide
• Benchmarks
• Use cases
• FAQ
• Troubleshooting
• Reference
• Article index

More README Files

• Benchmarks README
• Examples README
• Articles README
• Reference README

Example Packages and Scenarios

• AI prompt compression example
• Log payload storage example
• LLM response validation example
• HTTP TOON response example
• Eloquent Toonable trait example

Branding Asset

• Social preview source

License

Released under the MIT License.