What is T3Toon? 

T3Toon (Token-Optimized Object Notation) is a compact, human-readable, and token-efficient data format designed specifically for AI and LLM integrations in TYPO3 CMS.

It transforms large JSON or PHP arrays into a format that:

• Reduces token usage by up to 70% compared to JSON
• Maintains human readability (YAML-like structure)
• Preserves complete data structure and key order
• Supports bidirectional conversion (JSON ⇄ TOON)

Use Cases 

T3Toon is perfect for:

• AI Prompt Engineering: Compress structured data for LLMs (ChatGPT, Gemini, Claude, Mistral)
• Token Optimization: Reduce token usage and API costs
• Data Preprocessing: Streamline complex structured inputs
• Logging & Debugging: Store compact, readable structured logs
• Database Storage: Reduce JSON storage size while preserving structure
• Developer Tools: Perfect for previews and compact dashboards (e.g. TOON Playground backend module)

Why T3Toon? 

When working with AI APIs, every token counts. Traditional JSON format includes:

• Redundant quotes around keys and string values
• Verbose syntax (braces, brackets, commas)
• Repeated structural markers

T3Toon eliminates this overhead while maintaining:

• Complete data fidelity
• Human readability
• Easy parsing and conversion
• Support for complex nested structures

Example Comparison 

JSON Format (7.7 KB,  1,930 tokens):

{
  "user": "ABC",
  "message": "Hello, how are you?",
  "tasks": [
    {"id": 1, "done": false},
    {"id": 2, "done": true}
  ]
}

TOON Format (2.5 KB,  640 tokens):

user: ABC
message: Hello\, how are you?
tasks:
  items[2]{done,id}:
    false,1
    true,2

Result:  67% size reduction and  66.8% fewer tokens while retaining complete data accuracy.

Format and specification 

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. The current format remains stable and suitable for TYPO3 AI integrations.

Optional primitive array header ([N]: v1,v2,v3) can be enabled via EncodeOptions or extension configuration for spec-style output.

Bidirectional Conversion 

Convert between JSON and TOON format seamlessly:

• JSON → TOON: Compress data for AI prompts (encode/convert)
• TOON → JSON: Restore original structure (decode)

Readable & Compact 

• YAML-like structure that's human-friendly
• Configurable indent and delimiter (comma or tab)
• Presets: compact (indent 0), readable (indent 4), tabular (tab delimiter)

Token-Efficient 

• Save up to 70% tokens on every AI prompt
• Reduces API costs significantly
• Optimized for ChatGPT, Gemini, Claude, and Mistral models
• Built-in token estimation (words, chars, tokens_estimate)

Preserves Key Order 

• Ensures deterministic data output
• Maintains structure integrity
• Critical for consistent AI responses

Per-Call Options (EncodeOptions / DecodeOptions) 

• EncodeOptions: Override indent, delimiter, maxPreviewItems, escapeStyle, minRowsToTabular, primitiveArrayHeader per call
• DecodeOptions: Control scalar type coercion (default vs lenient)
• Presets: EncodeOptions::compact(), EncodeOptions::readable(), EncodeOptions::tabular(); DecodeOptions::lenient()

Static and Instance API 

• Static API: Toon::encodeStatic(), Toon::decodeStatic(), Toon::convertStatic(), Toon::estimateTokensStatic() — no dependency injection required
• Instance API: $toon->encode(), $toon->decode(), etc. — recommended for TYPO3 DI and testing

Error Handling 

• ToonDecodeException for malformed TOON input, with getLineNumber() and getSnippet() for easier debugging
• Base ToonException for all TOON-related errors

Global Helpers 

• toon(), toon_decode(), toon_compact(), toon_readable(), toon_decode_lenient(), toon_estimate_tokens() — no use required after extension load

Fluid ViewHelpers 

• toon:encode, toon:decode, toon:estimateTokens — use TOON directly in Fluid templates with optional presets (default, compact, readable, tabular; lenient for decode)

Backend Module (TOON Playground) 

• Tools → TOON Playground: Encode JSON to TOON, decode TOON to JSON, encode compact, view token estimate and errors in the browser

Built-in Analytics 

• Measure token, byte, and compression performance via estimateTokens() / estimateTokensStatic()
• Compare JSON vs TOON metrics

Complex Nested Array Support 

• Fully supports deeply nested associative and indexed arrays
• Handles multi-level structures
• Optional primitive array header [N]: v1,v2,v3 for spec-style output

TYPO3 Integration 

• Native TYPO3 extension
• Follows TYPO3 coding standards
• Dependency injection support
• Service-based architecture
• Extension configuration (Install Tool) and programmatic options

Requirements 

• TYPO3 CMS 12.4.0 – 14.9.99
• PHP 8.1 or higher

Update the database scheme 

Open your TYPO3 backend with system maintainer permissions.

In the module menu to the left navigate to Admin Tools > Maintenance, then click on Analyze database and create all.

Clear all caches 

In the same module Admin Tools > Maintenance you can also conveniently clear all caches by clicking the button Flush cache.

Verify installation 

After installation, you can verify that the extension is loaded by checking the extension manager or by using the service in your code:

Instance API (recommended in TYPO3):

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

$toon = GeneralUtility::makeInstance(Toon::class);
$result = $toon->convert(['test' => 'value']);
echo $result; // Should output: test: value

Static API (convenience):

use RRP\T3Toon\Service\Toon;

$result = Toon::convertStatic(['test' => 'value']);
echo $result; // test: value

Backend module: In the TYPO3 backend, go to Tools > TOON Playground to encode and decode TOON in the browser.

Basic encoding (JSON → TOON) 

Convert PHP arrays or JSON strings to TOON format.

Instance API (recommended in TYPO3 for dependency injection):

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

$data = [
    'user' => 'ABC',
    'message' => 'Hello, how are you?',
    'tasks' => [
        ['id' => 1, 'done' => false],
        ['id' => 2, 'done' => true],
    ],
];

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

Static API (convenience, no DI):

use RRP\T3Toon\Service\Toon;

$toon = Toon::convertStatic($data);
// or
$toon = Toon::encodeStatic($data);

Output:

user: ABC
message: Hello\, how are you?
tasks:
  items[2]{done,id}:
    false,1
    true,2

Basic decoding (TOON → PHP) 

Convert TOON format back to PHP arrays.

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

$toon = <<<TOON
user: ABC
tasks:
  items[2]{id,done}:
    1,false
    2,true
TOON;

$data = GeneralUtility::makeInstance(Toon::class)->decode($toon);
// or: $data = Toon::decodeStatic($toon);
print_r($data);

Output:

Array
(
    [user] => ABC
    [tasks] => Array
        (
            [0] => Array ( [id] => 1, [done] => false )
            [1] => Array ( [id] => 2, [done] => true )
        )
)

Per-call options (EncodeOptions / DecodeOptions) 

Override encoding or decoding behavior for a single call without changing extension configuration.

Encoding presets:

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

$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 (lenient = no scalar coercion):

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

$data = Toon::decodeStatic($toon);                              // use extension config
$strings = Toon::decodeStatic($toon, DecodeOptions::lenient());  // keep "true", "42" as strings

See Options (EncodeOptions & DecodeOptions) for full details.

Token estimation 

Estimate the number of tokens in a TOON string (heuristic based on words and characters).

use RRP\T3Toon\Service\Toon;

$toonService = GeneralUtility::makeInstance(Toon::class);
$toon = $toonService->convert($data);
$stats = $toonService->estimateTokens($toon);
// or: $stats = Toon::estimateTokensStatic($toon);

print_r($stats);

Output:

Array
(
    [words] => 20
    [chars] => 182
    [tokens_estimate] => 19
)

Error handling 

Decoding malformed TOON throws RRP\T3Toon\Exception\ToonDecodeException with line number and snippet. See Error handling.

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

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

Working with JSON strings 

The encoder accepts JSON strings; they are decoded to arrays and then converted to TOON.

$json = '{"user":"ABC","active":true}';
$toon = Toon::encodeStatic($json);
echo $toon;

Output:

user: ABC
active: true

Complex nested structures 

T3Toon handles deeply nested structures. The output remains human-readable, reversible, and compact.

$data = [
    'user' => [
        'id' => 101,
        'roles' => ['admin', 'editor'],
        'profile' => [
            'location' => ['city' => 'ABC', 'country' => 'India'],
        ],
    ],
    'orders' => [ ['order_id' => 'ORD-1001', 'amount' => 1998] ],
];
$toon = Toon::encodeStatic($data);

Further reading 

• Options (EncodeOptions & DecodeOptions)
• Error handling
• Global helpers
• Fluid ViewHelpers
• Backend module (TOON Playground)

Access configuration 

Navigate to Admin Tools > Settings > Extension Configuration and select T3Toon – Token-Efficient Data Format for TYPO3 AI.

Extension configuration options 

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

Per-call options 

You can override encoding and decoding behavior per call using EncodeOptions and DecodeOptions instead of changing global configuration. See Options (EncodeOptions & DecodeOptions).

Programmatic access 

use RRP\T3Toon\Utility\ToonHelper;

$config = ToonHelper::getConfig();
// Returns full config including defaults:
// [
//     'indent' => 2,
//     'delimiter' => ',',
//     'escape_style' => 'backslash',
//     'min_rows_to_tabular' => 2,
//     'max_preview_items' => 200,
//     'coerce_scalar_types' => true,
//     'primitive_array_header' => false,
// ]

$merged = ToonHelper::getConfigMerged(['indent' => 4]);
// Merges overrides with extension config (e.g. for one-off encoding).

EncodeOptions 

Class: RRP\T3Toon\Domain\Model\EncodeOptions

Constructor parameters (all optional; null = use extension config):

• indent (int|null) — Spaces per indentation level (default from config: 2)
• delimiter (string|null) — Field delimiter for tabular rows: EncodeOptions::DELIMITER_COMMA (',') or EncodeOptions::DELIMITER_TAB ("\t")
• maxPreviewItems (int|null) — Maximum rows to emit in tabular blocks
• escapeStyle (string|null) — Escape style (e.g. 'backslash')
• minRowsToTabular (int|null) — Minimum rows before using tabular format
• primitiveArrayHeader (bool|null) — If true, emit primitive sequential arrays as single line [N]: v1,v2,v3 (spec-style)

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

// Default: use extension config
$toon = Toon::encodeStatic($data, EncodeOptions::default());
// or pass null
$toon = Toon::encodeStatic($data, null);

// Compact: indent 0, comma delimiter
$toon = Toon::encodeStatic($data, EncodeOptions::compact());

// Readable: indent 4
$toon = Toon::encodeStatic($data, EncodeOptions::readable());

// Tabular: tab delimiter (spreadsheet-friendly)
$toon = Toon::encodeStatic($data, EncodeOptions::tabular());

// Custom: e.g. primitive array header
$options = new EncodeOptions(primitiveArrayHeader: true);
$toon = Toon::encodeStatic($data, $options);

DecodeOptions 

Class: RRP\T3Toon\Domain\Model\DecodeOptions

Constructor parameters:

• coerceScalarTypes (bool|null) — If true, convert "true"/"false"/"123" to PHP types; if false, keep as strings (default from config: true)

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

// Default: use extension config (coerce scalar types)
$data = Toon::decodeStatic($toon, DecodeOptions::default());

// Lenient: do not coerce; keep "true", "42" as strings
$data = Toon::decodeStatic($toon, DecodeOptions::lenient());

Merging with extension config 

Internally, non-null option properties are merged with extension configuration for that single call. Use ToonHelper::getConfigMerged() if you need the merged config array (e.g. for custom logic).

Exception hierarchy 

• ToonException — Base exception for all TOON-related errors
• ToonDecodeException — Thrown when TOON input cannot be parsed (invalid key:value format, malformed structure, etc.)

ToonDecodeException API 

• getMessage() — Full message, including "Line N: ..." and snippet when available
• getLineNumber(): int — One-based line number where the error occurred (0 if unknown)
• getSnippet(): ?string — The line content that caused the error (or null)

Example 

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

$input = "user: ABC\ninvalid-line-without-colon\nkey: value";

try {
    $data = Toon::decodeStatic($input);
} catch (ToonDecodeException $e) {
    echo $e->getMessage();       // e.g. "Line 2: Invalid key:value format"
    echo $e->getLineNumber();    // 2
    echo $e->getSnippet();        // "invalid-line-without-colon"
}

Best practices 

• Always catch ToonDecodeException when decoding user-provided or external TOON input.
• Use getLineNumber() and getSnippet() in logs or user-facing error messages to help fix invalid data.
• For other TOON-related errors (e.g. invalid options), catch the base ToonException if you need a single handler.

Available functions 

$toon = toon(['name' => 'TOON']);
$compact = toon($data, \RRP\T3Toon\Domain\Model\EncodeOptions::compact());

$data = toon_decode($toonString);

$toon = toon_compact($data);

$toon = toon_readable($data);

$data = toon_decode_lenient($toonString);

$stats = toon_estimate_tokens($toonString);
echo $stats['tokens_estimate'];

When to use 

• Quick scripts or hooks where you prefer not to inject the Toon service.
• Legacy or non-Extbase code where global functions are acceptable.

For dependency injection and testability, prefer the Toon service (instance or static) in PHP classes.

Namespace 

In your Fluid template, add:

xmlns:toon="http://typo3.org/ns/RRP/T3Toon/ViewHelpers"

Or ensure the namespace is available (registered in ext_localconf as toon).

toon:encode 

Encodes a value to TOON format.

Arguments:

• value (required) — Data to encode (array, object, scalar)
• options (optional) — Preset: default, compact, readable, tabular; default: default

Examples:

<toon:encode value="{data}" />
<toon:encode value="{data}" options="compact" />
<toon:encode value="{data}" options="readable" />
<toon:encode value="{data}" options="tabular" />

toon:decode 

Decodes a TOON string to a PHP array. You can assign the result to a variable and use it in child content (e.g. f:for), or output JSON.

Arguments:

• toon (required) — TOON-formatted string to decode
• as (optional) — Variable name to assign the decoded array to; if set, child content is rendered and the variable is available inside
• lenient (optional) — If true, do not coerce scalar types; default: false

Examples:

<!-- Output decoded as JSON -->
<toon:decode toon="{toonString}" />

<!-- Assign to variable and use in loop -->
<toon:decode toon="{toonString}" as="decoded">
    <f:for each="{decoded}" as="item">
        {item.name}
    </f:for>
</toon:decode>

<!-- Lenient decode (keep "true", "42" as strings) -->
<toon:decode toon="{toonString}" as="decoded" lenient="true">
    ...
</toon:decode>

toon:estimateTokens 

Estimates token count for a TOON string. Outputs tokens_estimate by default, or assigns the full stats array to a variable.

Arguments:

• toon (required) — TOON string to estimate
• as (optional) — Variable name to assign the result (keys: words, chars, tokens_estimate); if set, child content is rendered

Examples:

<!-- Output estimated token count -->
<toon:estimateTokens toon="{toonString}" />

<!-- Use full stats in child content -->
<toon:estimateTokens toon="{toonString}" as="stats">
    Words: {stats.words}, Chars: {stats.chars}, Tokens: {stats.tokens_estimate}
</toon:estimateTokens>

Full template example 

<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
      xmlns:toon="http://typo3.org/ns/RRP/T3Toon/ViewHelpers"
      data-namespace-typo3-fluid="true">
  <toon:encode value="{myData}" options="readable" />
  <toon:decode toon="{toonText}" as="decoded">
    <f:for each="{decoded}" as="item">…</f:for>
  </toon:decode>
  <toon:estimateTokens toon="{toonText}" as="stats">{stats.tokens_estimate}</toon:estimateTokens>
</html>

Access 

In the TYPO3 backend menu, go to Tools → TOON Playground.

Features 

• Input area — Paste JSON (for encoding) or TOON text (for decoding).
• Encode to TOON — Converts the pasted JSON to TOON format using default encoding options.
• Decode from TOON — Converts the pasted TOON text to JSON (pretty-printed).
• Encode (compact) — Converts the pasted JSON to TOON using compact options (indent 0).
• Output area — Shows the result (TOON or JSON) after an action.
• Estimated tokens — Displays an approximate token count for the result when available.
• Error messages — If input is invalid (e.g. invalid JSON for encode, malformed TOON for decode), an error message is shown.

Workflow 

1. Paste JSON into the input field and click Encode to TOON or Encode (compact) to get TOON output.
2. Or paste TOON into the input field and click Decode from TOON to get JSON.
3. Check the output area and the estimated tokens. Fix any errors reported if the input was invalid.

Use cases 

• Quick testing — Verify how your data looks in TOON format.
• Token estimation — Compare token counts for JSON vs TOON for the same data.
• Debugging — Decode TOON strings from logs or API responses to inspect structure.
• Documentation and demos — Show TOON format to colleagues or in training.

Requirements 

• Backend user must have access to the Tools module group (standard for editors and admins).
• Extension EXT:rrp_t3toon must be installed and active.

Main service class: Toon 

Class: RRP\T3Toon\Service\Toon

The main service provides instance and static methods for converting between PHP arrays/JSON and TOON format, and for token estimation. Pass null for options to use extension configuration.

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

$toon = GeneralUtility::makeInstance(Toon::class);
$result = $toon->convert($data);
$decoded = $toon->decode($result);
$stats = $toon->estimateTokens($result);

$compact = Toon::encodeStatic($data, EncodeOptions::compact());

Internal services 

Utility classes 

Domain models (options) 

Extension configuration 

The extension configuration is stored in the TYPO3 Extension Manager (Install Tool) and is read by the service. Additional defaults (indent, delimiter, primitive_array_header) are applied in code when not set. Access the full config programmatically via ToonHelper::getConfig().

Configuration array structure 

[
    'indent' => 2,                    // int, spaces per level (code default)
    'delimiter' => ',',               // string, ',' or "\t" (code default)
    'escape_style' => 'backslash',    // string, from Install Tool
    'min_rows_to_tabular' => 2,       // int, from Install Tool
    'max_preview_items' => 200,       // int, from Install Tool
    'coerce_scalar_types' => true,    // bool, from Install Tool
    'primitive_array_header' => false, // bool, code default
]

Install Tool (Extension Configuration) provides: escape_style, min_rows_to_tabular, max_preview_items, coerce_scalar_types. The service adds defaults for indent, delimiter, and primitive_array_header when not present.

Accessing configuration 

use RRP\T3Toon\Utility\ToonHelper;

$config = ToonHelper::getConfig();
$indent = $config['indent'];
$merged = ToonHelper::getConfigMerged(['indent' => 4]);

Configuration via Extension Manager 

Navigate to Admin Tools > Settings > Extension Configuration and select T3Toon – Token-Efficient Data Format for TYPO3 AI.

EncodeOptions and DecodeOptions (per-call) 

See Options (EncodeOptions & DecodeOptions) for overriding encoding/decoding per call instead of changing global configuration.

ToonException 

Class: RRP\T3Toon\Exception\ToonException

Base exception for all TOON-related errors. Extends \Exception.

Use this when catching any T3Toon exception in a single handler.

ToonDecodeException 

Class: RRP\T3Toon\Exception\ToonDecodeException

Thrown when TOON input cannot be decoded (malformed key:value format, invalid structure, etc.). Extends ToonException.

use RRP\T3Toon\Exception\ToonDecodeException;

try {
    $data = Toon::decodeStatic($input);
} catch (ToonDecodeException $e) {
    $line = $e->getLineNumber();
    $snippet = $e->getSnippet();
    // Log or display to user
}

toon:encode 

Encodes a value to TOON format.

Arguments:

• value (required, mixed) — Data to encode (array, object, scalar)
• options (optional, string) — Preset: default, compact, readable, tabular; default: default

Returns: TOON string (no child content).

Example:

<toon:encode value="{data}" options="readable" />

toon:decode 

Decodes a TOON string to a PHP array.

Arguments:

• toon (required, string) — TOON-formatted string to decode
• as (optional, string) — Variable name to assign the decoded array to; if set, child content is rendered and the variable is available inside
• lenient (optional, bool) — If true, do not coerce scalar types; default: false

Returns: If as is set, the rendered child content; otherwise JSON-encoded decoded array.

Examples:

<toon:decode toon="{toonString}" />
<toon:decode toon="{toonString}" as="decoded">
    <f:for each="{decoded}" as="item">…</f:for>
</toon:decode>
<toon:decode toon="{toonString}" as="decoded" lenient="true">…</toon:decode>

toon:estimateTokens 

Estimates token count for a TOON string.

Arguments:

• toon (required, string) — TOON string to estimate
• as (optional, string) — Variable name to assign the result (keys: words, chars, tokens_estimate); if set, child content is rendered

Returns: If as is set, the rendered child content; otherwise the string value of tokens_estimate.

Examples:

<toon:estimateTokens toon="{toonString}" />
<toon:estimateTokens toon="{toonString}" as="stats">{stats.tokens_estimate}</toon:estimateTokens>

Namespace registration 

The namespace is registered in ext_localconf.php:

$GLOBALS['TYPO3_CONF_VARS']['SYS']['fluid']['namespaces']['toon'] = ['RRP\T3Toon\ViewHelpers'];

In Fluid, use xmlns:toon="http://typo3.org/ns/RRP/T3Toon/ViewHelpers" or the short name toon if your TYPO3 version resolves it.