README

Token-Optimized Object Notation for AI & LLM Workflows

✨ What is TOON?

TOON (Token-Optimized Object Notation) is a TYPO3-native data format that transforms large JSON or PHP arrays into a compact, human-readable, and token-efficient structure, purpose-built for AI prompts and LLM contexts.

It helps you:

🔻 Reduce token usage (up to 60–75%)
💰 Lower AI API costs
🧠 Improve prompt clarity and context understanding
🔁 Convert data seamlessly between JSON ⇄ TOON

🚀 Key Features

🔁 Bidirectional conversion (JSON ⇄ TOON)
🧩 Compact, YAML-like and human-readable format
💰 Significant token and size reduction
📊 Built-in analytics and token estimation
🧠 Optimized for ChatGPT, Gemini, Claude, and Mistral
🆕 Supports deeply nested and complex data structures
🔒 Preserves key order and data integrity

📦 Installation

➤ TYPO3 Extension Repository (TER)

Install via the TYPO3 backend or directly from TER:

🔗 https://extensions.typo3.org/extension/rrp_t3toon

➤ Composer (Packagist)

Recommended for Composer-based TYPO3 projects: 🔗 https://packagist.org/packages/rrp/t3-toon

composer require rrp/t3-toon

🧠 Quick Usage Example

Static API (convenience, no DI):

use RRP\T3Toon\Service\Toon;

$data = ['user' => 'ABC', 'tasks' => [['id' => 1, 'done' => false], ['id' => 2, 'done' => true]]];
echo Toon::encodeStatic($data);
// or: Toon::convertStatic($data);

$decoded = Toon::decodeStatic($toonString);
$estimate = Toon::estimateTokensStatic($toonString);

Instance API (recommended in TYPO3 for dependency injection):

use RRP\T3Toon\Service\Toon;
use TYPO3\CMS\Core\Utility\GeneralUtility;

$toon = GeneralUtility::makeInstance(Toon::class);
echo $toon->convert($data);
$decoded = $toon->decode($toonString);

Output (TOON):

user: ABC
tasks:
  items[2]{id,done}:
    1,false
    2,true

Configuration options

Override encoding/decoding per call with EncodeOptions and DecodeOptions (null = use extension config from Install Tool):

use RRP\T3Toon\Domain\Model\EncodeOptions;
use RRP\T3Toon\Domain\Model\DecodeOptions;
use RRP\T3Toon\Service\Toon;

// Encoding: indent, delimiter (comma/tab), max_preview_items, etc.
$compact = Toon::encodeStatic($data, EncodeOptions::compact());   // indent 0
$readable = Toon::encodeStatic($data, EncodeOptions::readable()); // indent 4
$tabular = Toon::encodeStatic($data, EncodeOptions::tabular());  // tab delimiter

// Decoding: coerce scalar types (true/false, numbers) or keep as strings
$data = Toon::decodeStatic($toon);
$strings = Toon::decodeStatic($toon, DecodeOptions::lenient());   // no coercion

Extension config (Install Tool → Extension Manager → rrp_t3toon) provides defaults: escape_style, min_rows_to_tabular, max_preview_items, coerce_scalar_types.

Global helpers

When the extension is loaded, these global functions are available (no use needed):

toon($value);                    // encode (alias for Toon::encodeStatic)
toon_decode($toon);              // decode
toon_compact($value);            // encode with EncodeOptions::compact()
toon_readable($value);           // encode with EncodeOptions::readable()
toon_decode_lenient($toon);      // decode without scalar coercion
toon_estimate_tokens($toon);      // return ['words' => …, 'chars' => …, 'tokens_estimate' => …]

Fluid ViewHelpers

In Fluid templates, add the namespace and use:

<html xmlns:toon="http://typo3.org/ns/RRP/T3Toon/ViewHelpers" data-namespace-typo3-fluid="true">
  <!-- Encode data to TOON -->
  <toon:encode value="{data}" />
  <toon:encode value="{data}" options="readable" />
  <toon:encode value="{data}" options="compact" />

  <!-- Decode TOON and use in loop -->
  <toon:decode toon="{toonString}" as="decoded">
    <f:for each="{decoded}" as="item">…</f:for>
  </toon:decode>

  <!-- Estimate tokens -->
  <toon:estimateTokens toon="{toonString}" />
  <toon:estimateTokens toon="{toonString}" as="stats">{stats.tokens_estimate}</toon:estimateTokens>
</html>

Backend module (TOON Playground)

In the TYPO3 backend, go to Tools → TOON Playground to encode and decode TOON in the browser:

Paste JSON and click Encode to TOON or Encode (compact) to get TOON output.
Paste TOON and click Decode from TOON to get JSON.
The module shows estimated tokens and any error messages.

Error handling

Decoding malformed TOON throws RRP\T3Toon\Exception\ToonDecodeException with line number and snippet:

use RRP\T3Toon\Exception\ToonDecodeException;
use RRP\T3Toon\Service\Toon;

try {
    $data = Toon::decodeStatic($input);
} catch (ToonDecodeException $e) {
    // $e->getLineNumber(), $e->getSnippet()
}

📚 Documentation

Full documentation, configuration, and advanced usage are available here:

🔗 https://docs.typo3.org/p/rrp/t3-toon/main/en-us/

🧩 Use Cases

🤖 AI prompt engineering
📉 Token and cost optimization
🧠 Structured data preprocessing
🧾 Compact logging and debugging
🗄️ Optimized JSON storage
🔍 Developer tooling and previews

🧰 Compatibility

TYPO3	PHP	Extension Version
12.x – 14.x	≥ 8.1	v1.3.0

Format and spec (future)

This extension uses a TYPO3-optimized TOON format: key-value lines, items[N]{fields}: for tabular arrays, configurable indent and delimiter. It is inspired by but not identical to the TOON Specification. For full spec compliance and interoperability with other TOON implementations (e.g. toon-php), a future version may add a spec mode or an optional bridge to helgesverre/toon. Current format remains stable and suitable for TYPO3 AI integrations.

👨‍💻 Authors

Rohan Parmar
Himanshu Ramavat

💡 Contributing

Contributions are welcome and appreciated ❤️

Fork the repository
Create a feature branch
Commit your changes
Submit a Pull Request

📜 License

Licensed under the MIT License — free for personal and commercial use.

Made with 🧡 for the TYPO3 Developer

rrp / t3-toon

Maintainers

Package info

Statistics

Security