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

manoj / toon-php-lite

Maintainers

Details