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 

As of v4.0.0, this extension implements the official TOON Specification v3.3 and passes the complete language-agnostic conformance suite (389/389 encode + decode fixtures). Output is interoperable with other spec-compliant TOON implementations. The spec engine (RRP\T3Toon\Spec\Encoder / Decoder) is dependency-free; the TYPO3 service layer is a thin adapter over it.

Tabular arrays use the real key (users[2]{id,name}:), primitive arrays are inline (tags[3]: a,b,c), and the encoder supports comma/tab/pipe delimiters and optional key folding.

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, tab, or pipe)
• Presets: compact (indent 2), readable (indent 4), tabular (tab delimiter), folded (key folding)

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 (comma/tab/pipe), key folding, and flatten depth per call
• DecodeOptions: Toggle strict-mode validation and dotted-key path expansion
• Presets: EncodeOptions::compact(), ::readable(), ::tabular(), ::folded(); DecodeOptions::lenient(), ::expanded()

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

Usage Logs Module 

• Tools → TOON Logs: Every successful encode / convert call is recorded in tx_rrpt3toon_log (input size, output size, optimization %, settings_enabled snapshot, timestamp)
• Filters: date range, optimization status (enabled / disabled / all), minimum optimization %, page size
• Per-row delete and bulk delete with confirmation modal
• Sliding-window pagination, newest entries first
• CLI seed command for development: vendor/bin/typo3 t3toon:seed-logs <count> [days]

Global "enabled" Flag 

• Extension setting enabled toggles optimization globally without code changes
• When off, Toon::encode() / Toon::convert() return the input as-is; calls are still logged so you can audit which requests ran with optimization on vs off

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 2
$readable = Toon::encodeStatic($data, EncodeOptions::readable()); // indent 4
$tabular = Toon::encodeStatic($data, EncodeOptions::tabular());    // tab delimiter
$folded = Toon::encodeStatic($data, EncodeOptions::folded());      // safe key folding

Decoding (lenient = relaxed strict-mode validation):

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

$data = Toon::decodeStatic($toon);                               // use extension config (strict)
$lenient = Toon::decodeStatic($toon, DecodeOptions::lenient());  // relax strict-mode validation
$expanded = Toon::decodeStatic($toon, DecodeOptions::expanded()); // expand dotted keys into objects

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 

a.b.c: 1

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 the normalized config used by the spec engine:
// [
//     'enabled' => true,
//     'indent' => 2,
//     'delimiter' => ',',
//     'key_folding' => 'off',
//     'flatten_depth' => null,
//     'strict' => true,
//     'expand_paths' => 'off',
// ]

$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 (spec default 2; must be >= 1)
• delimiter (string|null) — Document delimiter: EncodeOptions::DELIMITER_COMMA (','), EncodeOptions::DELIMITER_TAB ("\t"), or EncodeOptions::DELIMITER_PIPE ('|')
• keyFolding (string|null) — 'off' (default) or 'safe' (collapse single-key object chains into dotted paths, spec §13.4)
• flattenDepth (int|null) — Max segments to fold when keyFolding is 'safe'; null = unbounded

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

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

// Compact: indent 2, comma delimiter (canonical)
$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());

// Folded: safe key folding (a.b.c: 1)
$toon = Toon::encodeStatic($data, EncodeOptions::folded());

// Custom: pipe delimiter + safe folding to depth 2
$options = new EncodeOptions(delimiter: '|', keyFolding: 'safe', flattenDepth: 2);
$toon = Toon::encodeStatic($data, $options);

DecodeOptions 

Class: RRP\T3Toon\Domain\Model\DecodeOptions

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

• strict (bool|null) — Enforce strict-mode validation (array length and row-width counts, indentation multiples, escape and delimiter consistency, blank lines inside arrays). Default true (spec §14). Set false for lenient parsing.
• expandPaths (string|null) — 'off' (default) keeps dotted keys literal; 'safe' expands unquoted dotted keys into nested objects (spec §13.4)

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

// Default: strict decoding
$data = Toon::decodeStatic($toon, DecodeOptions::default());

// Lenient: relax strict-mode validation
$data = Toon::decodeStatic($toon, DecodeOptions::lenient());

// Expanded: split dotted keys into nested objects
$data = Toon::decodeStatic($toon, DecodeOptions::expanded());

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, decode in lenient (non-strict) mode; 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 (relaxed strict-mode validation) -->
<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>

TOON Playground 

Use it to encode and decode TOON in the browser without writing code.

TOON Logs 

Every successful encode / convert call (from anywhere — Playground, ViewHelpers, global helpers, programmatic API, scheduler tasks, CLI commands) is recorded in the tx_rrpt3toon_log table. The Logs module surfaces that data for auditing and debugging.

vendor/bin/typo3 database:updateschema "*.add,*.change"

vendor/bin/typo3 t3toon:seed-logs 500       # 500 random rows over the last 30 days
vendor/bin/typo3 t3toon:seed-logs 100 7     # 100 rows over the last 7 days

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 Configuration (Install Tool) and read by the service. Defaults are applied in code when a value is not set. Access the full, normalized config programmatically via ToonHelper::getConfig().

Settings 

Normalized configuration array 

ToonHelper::getConfig() returns the values mapped for the spec engine:

[
    'enabled' => true,        // bool
    'indent' => 2,            // int (>= 1)
    'delimiter' => ',',       // ',' | "\t" | '|'
    'key_folding' => 'off',   // 'off' | 'safe'
    'flatten_depth' => null,  // int | null (null = unbounded)
    'strict' => true,         // bool
    'expand_paths' => 'off',  // 'off' | 'safe'
]

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, decode in lenient (non-strict) mode; 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.