Download the PHP package helgesverre/toon without Composer

TOON (Token-Oriented Object Notation)

A PHP port of toon-format/toon - a compact data format designed to reduce token consumption when sending structured data to Large Language Models.

Contents

• Configuration
• Development

What is TOON?

TOON is a compact, human-readable format for structured data optimized for LLM contexts. For format details and efficiency analysis, see the TOON Specification.

Installation

Install via Composer:

Requirements

• PHP 8.1 or higher

Quick Start

Try it online at ArrayAlchemy.

Basic Usage

Decoding TOON

TOON supports bidirectional conversion - you can decode TOON strings back to PHP arrays:

Note: TOON objects are decoded as PHP associative arrays, not objects.

Validating TOON

You can validate TOON input without decoding it to PHP values:

Tabular Format

TOON's most efficient format is for uniform object arrays:

Output:

Field names are declared once in the header, then each row contains only values. This is where TOON achieves the largest token savings compared to JSON.

See docs/EXAMPLES.md for more encoding examples.

Configuration Options

Customize encoding behavior with EncodeOptions:

Special Value Handling

String Quoting

TOON only quotes strings when necessary:

DateTime Objects

DateTime objects are automatically converted to ISO 8601 format:

PHP Enums

PHP enums are automatically normalized - BackedEnum values are extracted, UnitEnum names are used:

Special Numeric Values

Non-finite numbers are converted to null:

Helper Functions

TOON provides global helper functions for convenience:

Tutorials

Step-by-step guides for integrating TOON with LLM providers:

Getting Started

• Getting Started with TOON (10-15 min) Learn the basics: installation, encoding, configuration, and your first LLM integration.

Framework Integrations

• OpenAI PHP Client Integration (15-20 min) Integrate TOON with OpenAI's official PHP client. Covers messages, function calling, and streaming.

• Laravel + Prism AI Application (20-30 min) Build a complete Laravel AI chatbot using TOON and Prism for multi-provider support.

• Anthropic/Claude Integration (20-25 min) Leverage Claude's 200K context window with TOON optimization. Process large datasets efficiently.

Advanced Topics

• Token Optimization Strategies (20-25 min) Deep dive into token economics, RAG optimization, and cost reduction strategies.

• Building a RAG System with TOON and Ollama (30-40 min) Create a production-ready RAG pipeline with TOON, Ollama embeddings, and vector similarity search.

See the tutorials/ directory for all tutorials and learning paths.

Version Compatibility

This library tracks the TOON Specification. Major versions align with spec versions.

For format details and token efficiency analysis, see the TOON Specification.

Format Rules

Objects

• Key-value pairs with colons
• Indentation-based nesting (2 spaces by default)
• Empty objects shown as key:

Arrays

• Primitives: Inline format with length tags[3]: a,b,c
• Uniform objects: Tabular format with headers items[2]{sku,qty}: A1,2
• Mixed/non-uniform: List format with hyphens

Indentation

• 2 spaces per level (configurable)
• No trailing spaces
• No final newline

PHP-Specific Limitations

Numeric Key Handling

PHP automatically converts numeric string keys to integers in arrays:

The library handles this by quoting numeric keys when encoding.

Use Cases

TOON is ideal for:

• Sending structured data in LLM prompts
• Reducing token costs in API calls to language models
• Improving context window utilization
• Making data more human-readable in AI conversations

Note: TOON is optimized for LLM contexts and is not intended as a replacement for JSON in APIs or data storage.

Differences from JSON

TOON is not a strict superset or subset of JSON. Key differences:

• Bidirectional encoding and decoding (objects decode as associative arrays)
• Optimized for readability and token efficiency in LLM contexts
• Uses whitespace-significant formatting (indentation-based nesting)
• Includes metadata like array lengths and field headers for better LLM comprehension

Credits

• Original TypeScript implementation: toon-format/toon
• Specification: toon-format/spec
• PHP port: HelgeSverre

License

MIT License

Development

Testing

Specification Sync

Keep the library aligned with upstream spec changes:

The autofix command downloads the latest specification, then launches Claude Code in plan mode with the /spec-review prompt to analyze changes and propose implementation updates.

Benchmarks

See benchmarks/README.md for details.