README

🚀 TOON PHP Lite

A lightweight, dependency-free PHP library for encoding & decoding TOON (Token-Oriented Object Notation).

TOON is a compact, human-readable, LLM-friendly data format — an alternative to JSON that uses indentation, lists, and tabular rows for intuitive structure.

This library provides a lite encoder + decoder, suitable for everyday PHP applications, config parsing, and AI-driven workflows.

✨ Features

▶ Encoding & Decoding

• Simple API: Toon::encode() / Toon::decode()

• Full support for:

  • Nested objects via indentation

  • Primitive arrays: tags[3]: php,ai,iot

  • List arrays:

    tags[2]:
      - php
      - ai
    

  • Tabular arrays (key[n]{a,b,c}:):

    items[2]{sku,qty,price}:
      A1,2,9.99
      B2,1,14.5
    

▶ New in v0.4.0

• Triple-quoted multiline strings

  bio: """
  I am Manoj.
  I love PHP.
  """
  

• Minified TOON output (fully valid, no indentation)

  (new EncodeOptions())->setMinify(true);

• Complete test suite + round-trip stability checks

• PHPStan clean (level 8)

• Strict types everywhere

▶ Other Features

• Zero dependencies

• Detailed decode errors

  • row count mismatches
  • bad tabular rows
  • invalid indentation

• Comment support:

  • # comment
  • // comment
  • id: 1 # inline

Supports PHP 8.1 – 8.3

📦 Installation

via Packagist

composer require manoj/toon-php-lite

Development

git clone git@github.com:manojrammurthy/toon-php-lite.git
cd toon-php-lite
composer install

🚀 Quick Start

<?php

require __DIR__ . '/vendor/autoload.php';

use ToonLite\Toon;

$data = [
    'id'    => 1,
    'name'  => 'Manoj',
    'tags'  => ['php', 'ai', 'iot'],
    'items' => [
        ['sku' => 'A1', 'qty' => 2, 'price' => 9.99],
        ['sku' => 'B2', 'qty' => 1, 'price' => 14.5],
    ],
];

$toon = Toon::encode($data);
echo $toon;

$decoded = Toon::decode($toon);
var_dump($decoded);

Output

id: 1
name: Manoj
tags[3]: php,ai,iot
items[2]{sku,qty,price}:
  A1,2,9.99
  B2,1,14.5

📘 API Reference

ToonLite\Toon::encode(mixed $data, EncodeOptions|int|null $options = null): string

Encodes PHP values into valid TOON text.

Supported mappings

Objects

['id' => 1, 'name' => 'Manoj']

→

id: 1
name: Manoj

Primitive arrays

['php', 'ai', 'iot']

→

tags[3]: php,ai,iot

List arrays

['php', 'ai']

→

tags[2]:
  - php
  - ai

Tabular arrays

[
    ['sku'=>'A1', 'qty'=>2, 'price'=>9.99],
    ['sku'=>'B2', 'qty'=>1, 'price'=>14.5],
]

→

items[2]{sku,qty,price}:
  A1,2,9.99
  B2,1,14.5

✔ Multiline strings (NEW in v0.4.0)

"Hello\nWorld"

→

bio: """
Hello
World
"""

✔ Minify mode (NEW in v0.4.0)

$opts = (new EncodeOptions())->setMinify(true);
echo Toon::encode($data, $opts);

Output:

id:1
name:"Manoj"
tags[3]:php,ai,iot
items[2]{sku,qty,price}:A1,2,9.99 B2,1,14.5

ToonLite\Toon::decode(string $toon): mixed

Parses TOON back into PHP:

• associative arrays
• numeric arrays
• ints, floats, strings, bool, null
• multiline strings
• tabular & list arrays
• nested objects based on indentation

Comments

# top-level comment
id: 1  # inline
// comment
name: Manoj

🔧 Development

Run tests

vendor/bin/phpunit

Static analysis

composer phpstan

Code style (optional)

composer phpcs
composer php-cs-fixer

🗺 Roadmap

Completed in v0.4.0

• Multiline string support
• Minified output
• Strict decoder rewrite
• 100% PHPUnit coverage
• PHPStan level-8 clean
• EncodeOptions overhaul

Coming next

• Object-level annotations
• TOON schema validation
• Streaming decoder (very large files)
• Official TOON conformance tests
• Error messages with line/column numbers

📄 License

MIT © Manoj Ramamurthy