PHPackages helgesverre/toon - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Parsing & Serialization](/categories/parsing) 4. / 5. helgesverre/toon ActiveLibrary[Parsing & Serialization](/categories/parsing) helgesverre/toon ================ Token-Oriented Object Notation - A compact data format for reducing token consumption when sending structured data to LLMs v3.2.1(1mo ago)129198.5k↑99.1%1220MITPHPPHP ^8.1CI passing Since Oct 27Pushed 1mo ago2 watchersCompare [ Source](https://github.com/HelgeSverre/toon-php)[ Packagist](https://packagist.org/packages/helgesverre/toon)[ RSS](/packages/helgesverre-toon/feed)WikiDiscussions main Synced 2w ago READMEChangelog (10)Dependencies (9)Versions (12)Used By (20) TOON (Token-Oriented Object Notation) ===================================== [](#toon-token-oriented-object-notation) [![Packagist Version](https://camo.githubusercontent.com/c677ffea4ec8003545a61369146fe66e1cce7fcbd26427791dd1679c8284a539/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f68656c67657376657272652f746f6f6e)](https://packagist.org/packages/helgesverre/toon)[![Total Downloads](https://camo.githubusercontent.com/d86d3faf8128ef960d035c7937b082aed86de0a56b8f62746a8f4faa3791e6c0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f68656c67657376657272652f746f6f6e)](https://camo.githubusercontent.com/d86d3faf8128ef960d035c7937b082aed86de0a56b8f62746a8f4faa3791e6c0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f68656c67657376657272652f746f6f6e)[![License](https://camo.githubusercontent.com/6c8db93bb92d0bc82e5e7a5ce7c34915d456b1b7d74041c54d97e9720c3d9bd3/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f68656c67657376657272652f746f6f6e)](https://suno.com/song/ecb121f2-9db7-4f6a-880e-77a2aee7253f)[![Try it](https://camo.githubusercontent.com/c7fd347a1d67b454291ca103317f51267c301bbe595f919021a49358ab5046dd/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7472795f69742d4172726179416c6368656d792d344534354532)](https://arrayalchemy.com/?format=toon-php) A PHP port of [toon-format/toon](https://github.com/toon-format/toon) - a compact data format designed to reduce token consumption when sending structured data to Large Language Models. Contents -------- [](#contents) - [Quick Start](#quick-start) · [Basic Usage](#basic-usage) · [Decoding](#decoding-toon) · [Validating](#validating-toon) · [Configuration](#configuration-options) - [Tutorials](#tutorials) · [Version Compatibility](#version-compatibility) · [Development](#development) What is TOON? ------------- [](#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](https://github.com/toon-format/spec). Installation ------------ [](#installation) Install via Composer: ``` composer require helgesverre/toon ``` Requirements ------------ [](#requirements) - PHP 8.1 or higher Quick Start ----------- [](#quick-start) ``` use HelgeSverre\Toon\Toon; // Encode data echo Toon::encode(['user' => 'Alice', 'score' => 95]); // user: Alice // score: 95 // Decode back to PHP $data = Toon::decode("user: Alice\nscore: 95"); // ['user' => 'Alice', 'score' => 95] ``` Try it online at [ArrayAlchemy](https://arrayalchemy.com/?format=toon-php). Basic Usage ----------- [](#basic-usage) ``` use HelgeSverre\Toon\Toon; // Simple values echo Toon::encode('hello'); // hello echo Toon::encode(42); // 42 echo Toon::encode(true); // true echo Toon::encode(null); // null // Arrays echo Toon::encode(['a', 'b', 'c']); // [3]: a,b,c // Objects echo Toon::encode([ 'id' => 123, 'name' => 'Ada', 'active' => true ]); // id: 123 // name: Ada // active: true ``` Decoding TOON ------------- [](#decoding-toon) TOON supports bidirectional conversion - you can decode TOON strings back to PHP arrays: ``` use HelgeSverre\Toon\Toon; // Decode simple values $result = Toon::decode('42'); // 42 $result = Toon::decode('hello'); // "hello" $result = Toon::decode('true'); // true // Decode arrays $result = Toon::decode('[3]: a,b,c'); // ['a', 'b', 'c'] // Decode objects (returned as associative arrays) $toon = true] // Decode nested structures $toon = 'ada@example.com', 'metadata' => ['active' => true, 'score' => 9.5]]] ``` **Note**: TOON objects are decoded as PHP associative arrays, not objects. Validating TOON --------------- [](#validating-toon) You can validate TOON input without decoding it to PHP values: ``` use HelgeSverre\Toon\DecodeOptions; use HelgeSverre\Toon\Toon; // Strict validation (default) $isValid = Toon::validate("user: Alice\nscore: 95"); // true // Invalid TOON $isValid = Toon::validate('[3]: a,b'); // false // Lenient validation $isValid = Toon::validate('[3]: a,b', DecodeOptions::lenient()); // true ``` Tabular Format -------------- [](#tabular-format) TOON's most efficient format is for uniform object arrays: ``` echo Toon::encode([ 'users' => [ ['id' => 1, 'name' => 'Alice', 'role' => 'admin'], ['id' => 2, 'name' => 'Bob', 'role' => 'user'], ] ]); ``` Output: ``` users[2]{id,name,role}: 1,Alice,admin 2,Bob,user ``` 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](docs/EXAMPLES.md) for more encoding examples. Configuration Options --------------------- [](#configuration-options) Customize encoding behavior with `EncodeOptions`: ``` use HelgeSverre\Toon\EncodeOptions; // Custom indentation (default: 2) $options = new EncodeOptions(indent: 4); echo Toon::encode(['a' => ['b' => 'c']], $options); // a: // b: c // Tab delimiter instead of comma (default: ',') $options = new EncodeOptions(delimiter: "\t"); echo Toon::encode(['tags' => ['a', 'b', 'c']], $options); // tags[3\t]: a b c // Pipe delimiter $options = new EncodeOptions(delimiter: '|'); echo Toon::encode(['tags' => ['a', 'b', 'c']], $options); // tags[3|]: a|b|c ``` Special Value Handling ---------------------- [](#special-value-handling) ### String Quoting [](#string-quoting) TOON only quotes strings when necessary: ``` echo Toon::encode('hello'); // hello (no quotes) echo Toon::encode('true'); // "true" (quoted - looks like boolean) echo Toon::encode('42'); // "42" (quoted - looks like number) echo Toon::encode('a:b'); // "a:b" (quoted - contains colon) echo Toon::encode(''); // "" (quoted - empty string) echo Toon::encode("line1\nline2"); // "line1\nline2" (quoted - control chars) ``` ### DateTime Objects [](#datetime-objects) DateTime objects are automatically converted to ISO 8601 format: ``` $date = new DateTime('2025-01-01T00:00:00+00:00'); echo Toon::encode($date); // "2025-01-01T00:00:00+00:00" ``` ### PHP Enums [](#php-enums) PHP enums are automatically normalized - BackedEnum values are extracted, UnitEnum names are used: ``` enum Status: string { case ACTIVE = 'active'; case INACTIVE = 'inactive'; } enum Priority: int { case LOW = 1; case HIGH = 10; } enum Color { case RED; case GREEN; case BLUE; } // BackedEnum with string value echo Toon::encode(Status::ACTIVE); // active // BackedEnum with int value echo Toon::encode(Priority::HIGH); // 10 // UnitEnum (no backing value) echo Toon::encode(Color::BLUE); // BLUE // Array of enum cases echo Toon::encode(Priority::cases()); // [2]: 1,10 ``` ### Special Numeric Values [](#special-numeric-values) Non-finite numbers are converted to null: ``` echo Toon::encode(INF); // null echo Toon::encode(-INF); // null echo Toon::encode(NAN); // null ``` Helper Functions ---------------- [](#helper-functions) TOON provides global helper functions for convenience: ``` // Basic encoding $toon = toon($data); // Decoding $data = toon_decode($toonString); // Lenient decoding (forgiving parsing) $data = toon_decode_lenient($toonString); // Strict validation $isValid = toon_validate($toonString); // Lenient validation $isValid = toon_validate_lenient($toonString); // Compact (minimal indentation) $compact = toon_compact($data); // Readable (generous indentation) $readable = toon_readable($data); // Tabular (tab-delimited) $tabular = toon_tabular($data); // Compare with JSON $stats = toon_compare($data); // Returns: ['toon' => 450, 'json' => 800, 'savings' => 350, 'savings_percent' => '43.8%'] // Get size estimate $size = toon_size($data); // Estimate token count (4 chars/token heuristic) $tokens = toon_estimate_tokens($data); ``` Tutorials --------- [](#tutorials) Step-by-step guides for integrating TOON with LLM providers: ### Getting Started [](#getting-started) - **[Getting Started with TOON](tutorials/01-getting-started.md)** (10-15 min) Learn the basics: installation, encoding, configuration, and your first LLM integration. ### Framework Integrations [](#framework-integrations) - **[OpenAI PHP Client Integration](tutorials/02-openai-integration.md)** (15-20 min) Integrate TOON with OpenAI's official PHP client. Covers messages, function calling, and streaming. - **[Laravel + Prism AI Application](tutorials/03-laravel-prism-integration.md)** (20-30 min) Build a complete Laravel AI chatbot using TOON and Prism for multi-provider support. - **[Anthropic/Claude Integration](tutorials/06-anthropic-integration.md)** (20-25 min) Leverage Claude's 200K context window with TOON optimization. Process large datasets efficiently. ### Advanced Topics [](#advanced-topics) - **[Token Optimization Strategies](tutorials/04-token-optimization-strategies.md)** (20-25 min) Deep dive into token economics, RAG optimization, and cost reduction strategies. - **[Building a RAG System with TOON and Ollama](tutorials/05-rag-system-ollama.md)** (30-40 min) Create a production-ready RAG pipeline with TOON, Ollama embeddings, and vector similarity search. See the [`tutorials/`](tutorials) directory for all tutorials and learning paths. Version Compatibility --------------------- [](#version-compatibility) This library tracks the [TOON Specification](https://github.com/toon-format/spec). Major versions align with spec versions. LibrarySpecKey Changesv3.2.0v3.3`\uXXXX` control-character escapes, empty-array decoding (`[]`, `key: []`), strict rejection of `[03]` and duplicate keys, number canonical range, quoted-key colon fix, validation APIv3.1.0v3.0toJSON() method support, negative leading zeros fixv3.0.0v3.0List-item objects with tabular first field use depth +2 for rowsv2.0.0v2.0Removed `[#N]` length marker; decoder rejects legacy formatv1.4.0v1.3Full decoder, strict modev1.3.0v1.3PHP enum supportv1.2.0v1.3Empty array fixv1.1.0v1.3Benchmarks, justfilev1.0.0v1.3Initial releaseFor format details and token efficiency analysis, see the [TOON Specification](https://github.com/toon-format/spec). Format Rules ------------ [](#format-rules) ### Objects [](#objects) - Key-value pairs with colons - Indentation-based nesting (2 spaces by default) - Empty objects shown as `key:` ### Arrays [](#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 [](#indentation) - 2 spaces per level (configurable) - No trailing spaces - No final newline PHP-Specific Limitations ------------------------ [](#php-specific-limitations) ### Numeric Key Handling [](#numeric-key-handling) PHP automatically converts numeric string keys to integers in arrays: ``` // PHP automatically converts numeric keys $data = ['123' => 'value']; // Key becomes integer 123 echo Toon::encode($data); // "123": value (quoted as string) ``` The library handles this by quoting numeric keys when encoding. Use Cases --------- [](#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 --------------------- [](#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 ------- [](#credits) - Original TypeScript implementation: [toon-format/toon](https://github.com/toon-format/toon) - Specification: [toon-format/spec](https://github.com/toon-format/spec) - PHP port: [HelgeSverre](https://github.com/HelgeSverre) License ------- [](#license) [MIT License](LICENSE) Development ----------- [](#development) ### Testing [](#testing) ``` composer test # Run tests composer test:coverage # Generate coverage report composer analyse # Static analysis ``` ### Specification Sync [](#specification-sync) Keep the library aligned with upstream spec changes: ``` just sync-spec # Download latest SPEC.md from upstream just diff-spec # Show diff after download just autofix # Sync spec and launch Claude Code for compliance review ``` 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 [](#benchmarks) ``` cd benchmarks && composer install && composer run benchmark ``` See [benchmarks/README.md](benchmarks/README.md) for details. ### Health Score 58 — FairBetter than 98% of packages Maintenance92 Actively maintained with recent releases Popularity52 Moderate usage in the ecosystem Community30 Small or concentrated contributor base Maturity51 Maturing project, gaining track record Bus Factor1 Top contributor holds 95.9% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~28 days Recently: every ~59 days Total 10 Last Release 40d ago Major Versions v1.4.0 → v2.0.02025-11-13 v2.0.0 → v3.0.02025-11-26 ### Community Maintainers ![](https://www.gravatar.com/avatar/68f3958f40262d577ddc0596e4ba78b42c0409ebc7de948bab47edee392d5f68?d=identicon)[HelgeSverre](/maintainers/HelgeSverre) --- Top Contributors [![HelgeSverre](https://avatars.githubusercontent.com/u/1089652?v=4)](https://github.com/HelgeSverre "HelgeSverre (94 commits)")[![AmolKumarGupta](https://avatars.githubusercontent.com/u/88397611?v=4)](https://github.com/AmolKumarGupta "AmolKumarGupta (1 commits)")[![BriceFab](https://avatars.githubusercontent.com/u/24533309?v=4)](https://github.com/BriceFab "BriceFab (1 commits)")[![nikkyandrei](https://avatars.githubusercontent.com/u/4838087?v=4)](https://github.com/nikkyandrei "nikkyandrei (1 commits)")[![TonisOrmisson](https://avatars.githubusercontent.com/u/6357451?v=4)](https://github.com/TonisOrmisson "TonisOrmisson (1 commits)") --- Tags aidata-formatllmphpserializationtoken-compressiontoonlaravelcompressionaitokenserializationformatopenaioptimizationclaudellmanthropicgptpromptcost-reduction ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/helgesverre-toon/health.svg) ``` [![Health](https://phpackages.com/badges/helgesverre-toon/health.svg)](https://phpackages.com/packages/helgesverre-toon) ``` ### Alternatives [sbsaga/toon 🧠 TOON for Laravel — a compact, human-readable, and token-efficient data format for AI prompts & LLM contexts. Perfect for ChatGPT, Gemini, Claude, Mistral, and OpenAI integrations (JSON ⇄ TOON). 6665.2k](/packages/sbsaga-toon)[vizra/vizra-adk Vizra Agent Development Kit - A comprehensive Laravel package for building intelligent AI agents. 29636.7k](/packages/vizra-vizra-adk)[claude-php/claude-php-sdk-laravel Laravel integration for the Claude PHP SDK - Anthropic Claude API 5226.7k](/packages/claude-php-claude-php-sdk-laravel) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)