laravel-toon

Laravel TOON is a PHP package that implements the TOON format for compact, token-efficient data encoding and decoding within Laravel applications. It lets you encode complex data structures to a TOON string for lean API responses or LLM prompts, and decode TOON back to PHP arrays or collections. The package includes a global helper set and collection/model integrations, such as a toToon macro on Laravel collections and a toToon method on Eloquent models, making it easy to generate token-efficient payloads for MCP tool calls or LLM interactions. Use Toon::encode to convert data into TOON, and Toon::decode to restore the original structure, preserving types and nesting while reducing token usage by a substantial margin compared to JSON.

To use it in your application, install the package and leverage the provided helpers and macros. For example, encode a dataset before sending it to an MCP tool, or include a shortened context payload in LLM prompts. The library also supports tabular and list formats, inline arrays, and strict/decode options per configuration, allowing you to tailor token savings to your needs. The documentation examples show common usage patterns for encoding large result sets, transforming Laravel collections, and preparing API responses with optional TOON content negotiation.

In MCP workflows, you typically encode the data you return from tool calls, ensuring a smaller payload and better efficiency in token-constrained environments. You can integrate Toon::encode in a controller method that fetches data, and return the encoded string directly when the client requests application/toon, falling back to regular JSON otherwise.

Prerequisites:

• PHP 8.0 or higher
• Composer
• A Laravel application or PHP project where you want TOON integration

Step-by-step installation:

# In your Laravel project root
composer require mischasigtermans/laravel-toon

Publish configuration (optional, for customization):

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

Basic usage after installation:

use MischaSigtermans\Toon\Facades\Toon; // or use the helper functions: toon_encode/toon_decode

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

$toon = Toon::encode($data); // or toon_encode($data)
$original = Toon::decode($toon); // or toon_decode($toon)

If you prefer the fluent Collection API, you can use the toToon macro:

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

For Eloquent models, you can call toToon on a model instance:

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

Tips and considerations:

• TOON significantly reduces token usage for large responses; enable strict mode if decoding robustness is a priority.
• Safe strings can remain unquoted to minimize overhead; non-safe strings will be quoted per the TOON spec.
• If serving MCP API responses, you can detect Accept: application/toon and return Toon::encode($data) with Content-Type: application/toon, otherwise fall back to JSON.
• The package adheres to TOON v3.0 specifications, including tabular and list formats, inline arrays, and proper string escaping for special characters.
• If you run into encoding issues with complex nested structures, consider adjusting the Toon configuration (min_rows_for_table, delimiter, omit/omit_keys, etc.) to optimize token savings while preserving readability where needed.