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.1.0(5mo ago)11841.4k↑36.8%10[2 PRs](https://github.com/HelgeSverre/toon-php/pulls)9MITPHPPHP ^8.1 Since Oct 27Pushed 5mo ago1 watchersCompare [ Source](https://github.com/HelgeSverre/toon-php)[ Packagist](https://packagist.org/packages/helgesverre/toon)[ RSS](/packages/helgesverre-toon/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (8)Dependencies (4)Versions (9)Used By (9) 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) · [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. 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); // 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.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 50 — FairBetter than 96% of packages Maintenance71 Regular maintenance activity Popularity47 Moderate usage in the ecosystem Community21 Small or concentrated contributor base Maturity49 Maturing project, gaining track record Bus Factor1 Top contributor holds 98.6% 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 ~5 days Total 8 Last Release 164d 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 (69 commits)")[![AmolKumarGupta](https://avatars.githubusercontent.com/u/88397611?v=4)](https://github.com/AmolKumarGupta "AmolKumarGupta (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). 6115.6k](/packages/sbsaga-toon)[vizra/vizra-adk Vizra Agent Development Kit - A comprehensive Laravel package for building intelligent AI agents. 29026.1k](/packages/vizra-vizra-adk)[claude-php/claude-php-sdk-laravel Laravel integration for the Claude PHP SDK - Anthropic Claude API 5010.8k](/packages/claude-php-claude-php-sdk-laravel) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)