Laravel TOON

The most complete TOON implementation for Laravel, with full TOON v4.1 specification compliance. Listed as official Laravel implementation.

TOON (Token-Oriented Object Notation) is a compact, YAML-like format designed to reduce token usage when sending data to LLMs. This package achieves ~50% token reduction compared to JSON while maintaining full round-trip fidelity, backed by the official spec test suite.

Installation

composer require mischasigtermans/laravel-toon

Upgrading from 1.x? The 2.0.0 changelog says what changes and how to migrate.

Quick Start

use MischaSigtermans\Toon\Facades\Toon;

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

// Encode to TOON
$toon = Toon::encode($data);

// Decode back to array
$original = Toon::decode($toon);

Output:

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

Global Helper Functions

For convenience, global helper functions are available:

// Encode to TOON
$toon = toon_encode($data);

// Decode back to array
$original = toon_decode($toon);

Collection Macro: toToon

You can convert any Laravel collection directly to TOON format with the built-in toToon macro:

$collection = collect([
    ['id' => 1, 'name' => 'Alice'],
    ['id' => 2, 'name' => 'Bob'],
]);
$toon = $collection->toToon();

Output:

[2]{id,name}:
  1,Alice
  2,Bob

Eloquent Model: toToon

Eloquent models have a toToon method, similar to toJson and toArray:

$user = User::find(1);
$toon = $user->toToon();

Why TOON?

When building MCP servers or LLM-powered applications, every token counts. JSON's verbosity wastes context window space with repeated keys and structural characters.

JSON (124 bytes):

{"users":[{"id":1,"name":"Alice","role":"admin"},{"id":2,"name":"Bob","role":"user"},{"id":3,"name":"Carol","role":"user"}]}

TOON (67 bytes), 46% smaller:

users[3]{id,name,role}:
  1,Alice,admin
  2,Bob,user
  3,Carol,user

The field names are written once, so the saving grows with the row count: 56% at 10 rows, 59% at 50.

Benchmarks

For a typical paginated API response (50 records):

• JSON: ~7,597 tokens
• TOON: ~3,586 tokens
• Saved: ~4,000 tokens per request

Real-world benchmarks from a production application with 17,000+ records:

Features

Tabular Format

Arrays of uniform objects are encoded as compact tables:

$data = [
    ['id' => 1, 'name' => 'Alice', 'role' => 'admin'],
    ['id' => 2, 'name' => 'Bob', 'role' => 'user'],
];

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

Nested Field Groups

Nested objects that share one shape stay in the table. The header describes the nesting, rows stay flat:

$data = [
    ['id' => 1, 'author' => ['name' => 'Jane', 'email' => '[email protected]']],
    ['id' => 2, 'author' => ['name' => 'John', 'email' => '[email protected]']],
];

$toon = Toon::encode($data);
// [2]{id,author{name,email}}:
//   1,Jane,[email protected]
//   2,John,[email protected]

Groups nest to any depth. Keys containing dots stay literal keys.

Keyed Tables

Objects whose values are uniform objects collapse into a table whose rows carry their own keys:

$data = [
    'servers' => [
        'alpha' => ['host' => 'a.example.com', 'port' => 8080],
        'beta' => ['host' => 'b.example.com', 'port' => 9090],
    ],
];

$toon = Toon::encode($data);
// servers[2:]{host,port}:
//   alpha: a.example.com,8080
//   beta: b.example.com,9090

List Format

Arrays whose objects differ in shape use list format:

$data = [
    ['id' => 1, 'author' => ['name' => 'Jane']],
    ['id' => 2, 'author' => ['name' => 'John', 'email' => '[email protected]']],
];

$toon = Toon::encode($data);
// [2]:
//   - id: 1
//     author:
//       name: Jane
//   - id: 2
//     author:
//       name: John
//       email: [email protected]

Comments

The decoder skips full-line comments. The encoder never emits them.

Toon::decode("# Weekly export\nusers[1]{id,name}:\n  1,Alice");
// ['users' => [['id' => 1, 'name' => 'Alice']]]

Type Preservation

All scalar types are preserved through encode/decode:

$data = [
    'count' => 42,
    'price' => 19.99,
    'active' => true,
    'deleted' => false,
    'notes' => null,
];

$decoded = Toon::decode(Toon::encode($data));
// Types are preserved: int, float, bool, null

String Quoting (Spec-Compliant)

Strings containing special characters are automatically quoted per the TOON spec:

$data = ['message' => 'Hello, World: How are you?'];
$toon = Toon::encode($data);
// message: "Hello, World: How are you?"

$data = ['text' => "Line 1\nLine 2"];
$toon = Toon::encode($data);
// text: "Line 1\nLine 2"

Safe strings (alphanumeric, underscores, dots) remain unquoted for minimal overhead.

Configuration

Publish the config file:

php artisan vendor:publish --tag=toon-config

Basic Options

// config/toon.php
return [
    // Arrays with fewer items use list format instead of tables
    'min_rows_for_table' => 1,

    // Delimiter for array values: ',' (default), '\t' (tab), or '|' (pipe)
    'delimiter' => ',',

    // Strict mode for decoding (throws on malformed input)
    'strict' => true,
];

Token-Saving Options

return [
    // Omit values to save tokens: 'null', 'empty', 'false', or 'all'
    'omit' => ['null', 'empty'],

    // Always skip these keys
    'omit_keys' => ['created_at', 'updated_at'],

    // Shorten verbose keys
    'key_aliases' => [
        'description' => 'desc',
        'organization_id' => 'org_id',
    ],
];

Value Transformation

return [
    // Format dates (DateTime objects and ISO strings)
    'date_format' => 'Y-m-d',

    // Truncate long strings (adds ... suffix)
    'truncate_strings' => 100,

    // Limit decimal places for floats
    'number_precision' => 2,
];

Utility Methods

Measure Savings

$data = User::with('roles')->get()->toArray();

$diff = Toon::diff($data);
// [
//     'json_chars' => 12500,
//     'toon_chars' => 5200,
//     'saved_chars' => 7300,
//     'savings_percent' => 58.4,
// ]

Encode Specific Keys Only

$users = User::all()->toArray();

// Only include id and name, exclude email, password, etc.
$toon = Toon::only($users, ['id', 'name']);

Use Cases

MCP Servers

Reduce token usage when returning data from MCP tool calls:

public function handle(): string
{
    $users = User::with('roles')->limit(100)->get();

    return Toon::encode([
        'count' => $users->count(),
        'users' => $users->toArray(),
    ]);
}

LLM Context

Pack more data into your context window:

$context = Toon::encode([
    'conversation' => $messages,
    'user_profile' => $user->toArray(),
    'recent_orders' => $orders->toArray(),
]);

$response = $llm->chat([
    ['role' => 'system', 'content' => "Context:\n{$context}"],
    ['role' => 'user', 'content' => $question],
]);

API Responses

Optional TOON responses for token-conscious clients:

public function index(Request $request)
{
    $data = Product::paginate()->toArray();

    if ($request->header('Accept') === 'application/toon') {
        return response(Toon::encode($data))
            ->header('Content-Type', 'application/toon');
    }

    return response()->json($data);
}

Spec Compliance

Targets toon-spec: 4.1.

This package implements the TOON v4.1 specification and passes the official specification test suite. Key compliance features:

• String quoting: Safe strings unquoted, special characters properly escaped (\n, \r, \t, \", \\, \uXXXX)
• Delimiter support: Comma (default), tab, and pipe delimiters
• Tabular format: Compact tables for arrays of uniform objects, with nested field groups ([N]{id,author{name}}:)
• Keyed tables: Objects of uniform objects (key[N:]{fields}:)
• List format: Arrays of non-uniform objects ([N]: with - field: items)
• Inline arrays: Primitive arrays on a single line (key[N]: a,b,c)
• Comments: Full-line # comments are skipped when decoding
• Strict mode: Optional validation during decoding

Host-type mapping:

• Objects decode to associative arrays. PHP casts integer-like keys ("42") to int, and an empty object decodes to [].
• Integers beyond PHP_INT_MAX decode as float.
• DateTimeInterface encodes as an ISO 8601 string, BackedEnum as its value, Arrayable, Traversable and JsonSerializable as their array form, Stringable as its string.
• In non-strict mode, each leading tab counts as one indentation level.

Testing

composer test

The test suite runs every fixture from the official TOON spec test suite plus the package's own feature tests. Install the fixtures with npm install first.

Requirements

• PHP 8.2+
• Laravel 12 or 13

Credits

• Mischa Sigtermans

License

MIT