Compact, human-readable, and token-efficient structured data for AI prompts, logs, and Laravel workflows
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
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
composer require sbsaga/toonOptional config publishing:
php artisan vendor:publish --provider="Sbsaga\Toon\ToonServiceProvider" --tag=configFacade 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();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\Toonablestrict_modedelimitercompatibility_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',The repository includes a synthetic benchmark fixture and runner:
Run it locally:
php benchmarks/run.php benchmarks/fixtures/paginated-users.jsonCurrent 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
- 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
- Docs index
- Quickstart
- Format and compatibility
- Syntax cheatsheet
- LLM integration guide
- Media type and files
- When not to use TOON
- Migration guide
- Benchmarks
- Use cases
- FAQ
- Reference
- Article index
- AI prompt compression example
- Log payload storage example
- LLM response validation example
- HTTP TOON response example
- Eloquent Toonable trait example
Released under the MIT License.