README

PHP implementation of TOON (Token-Oriented Object Notation) – A lightweight, compact serialization format designed to reduce token usage in Large Language Model (LLM) prompts by 30-60% compared to JSON.

Features

🎯 30-60% token reduction compared to JSON for LLM prompts
🔄 100% lossless round-trip compatibility with JSON-like structures
📊 Tabular format for uniform arrays of objects
🪶 Lightweight with zero runtime dependencies
✅ PSR-12 code style compliant
📦 PSR-4 autoloading
🧪 Fully tested with PHPUnit

What is TOON?

TOON combines YAML-like indentation for nested objects with CSV-like tabular formats for uniform arrays, making it ideal for structured data transmission to LLMs. It eliminates unnecessary JSON syntax (brackets, quotes for simple strings, repeated keys) while maintaining human-readability.

Example Comparison

JSON (175 characters):

{
  "users": [
    {"id": 1, "name": "Alice", "email": "alice@example.com"},
    {"id": 2, "name": "Bob", "email": "bob@example.com"}
  ]
}

TOON (98 characters - 44% smaller):

users:
  [2,]{id,name,email}:
    1,Alice,alice@example.com
    2,Bob,bob@example.com

Installation

Install via Composer:

composer require toonphp/toon

Usage

Encoding (PHP Array → TOON)

<?php
use ToonPhp\Toon;

// Simple object
$user = [
    'name' => 'Alice',
    'age' => 30,
    'active' => true
];

$toon = Toon::encode($user);
// Output:
// name: Alice
// age: 30
// active: true

// Array of objects (tabular format)
$users = [
    ['id' => 1, 'name' => 'Alice', 'email' => 'alice@example.com'],
    ['id' => 2, 'name' => 'Bob', 'email' => 'bob@example.com'],
];

$toon = Toon::encode($users);
// Output:
// [2,]{id,name,email}:
//   1,Alice,alice@example.com
//   2,Bob,bob@example.com

// Simple array
$fruits = ['apple', 'banana', 'cherry'];
$toon = Toon::encode($fruits);
// Output: [3]: apple,banana,cherry

Decoding (TOON → PHP Array)

<?php
use ToonPhp\Toon;

$toon = <<<TOON
name: Alice
age: 30
active: true
TOON;

$data = Toon::decode($toon);
// Result: ['name' => 'Alice', 'age' => 30, 'active' => true]

// Decode tabular array
$toon = <<<TOON
[2,]{id,name}:
  1,Alice
  2,Bob
TOON;

$users = Toon::decode($toon);
// Result: [
//   ['id' => 1, 'name' => 'Alice'],
//   ['id' => 2, 'name' => 'Bob']
// ]

Round-Trip Example

<?php
use ToonPhp\Toon;

$original = [
    'project' => 'TOON PHP',
    'version' => '1.0.0',
    'features' => ['encoding', 'decoding', 'round-trip'],
];

$encoded = Toon::encode($original);
$decoded = Toon::decode($encoded);

assert($original === $decoded); // ✓ Perfect round-trip!

TOON Format Rules

Primitives

Strings: No quotes for simple strings (name: Alice). Quotes required for strings with spaces/special chars (message: "hello world").
Numbers: As-is (age: 30, pi: 3.14)
Booleans: true / false
Null: null

Objects

Key-value pairs with 2-space indentation for nesting:

user:
  name: Alice
  age: 30

Arrays

Tabular format (uniform objects with same keys):

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

Simple array (primitives):

[3]: apple,banana,cherry

Mixed arrays (different types/structures):

[2]:
  - value1
  - value2

Development

Running Tests

composer install
vendor/bin/phpunit

Code Style

This project follows PSR-12 coding standards. To check/fix code style:

composer require --dev friendsofphp/php-cs-fixer
vendor/bin/php-cs-fixer fix --rules=@PSR12

Examples

Run the included examples:

php examples/simple_encode.php
php examples/simple_decode.php

Requirements

PHP ^8.1
ext-json

Credits

PHP Port: Tahir Ali Channa
Original TOON Specification: Johann Schopplich (@johannschopplich)
Original Repository: toon-format/toon

License

MIT License - see LICENSE file for details.

This PHP port is based on the original TOON specification created by Johann Schopplich and maintained by the toon-format organization.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Links

Made with ❤️ for the LLM community

toonphp / toon

Maintainers

Details