{"id":33973571,"url":"https://github.com/iamgerwin/toon-php","last_synced_at":"2026-01-25T07:03:44.503Z","repository":{"id":323257950,"uuid":"1092646152","full_name":"iamgerwin/toon-php","owner":"iamgerwin","description":"A lightweight, fast TOON (Token-Oriented Object Notation) library for PHP. Optimized for LLM contexts. PHP 7.0-8.0 [legacy] and 8.1 and up [modern] support.","archived":false,"fork":false,"pushed_at":"2025-12-02T16:39:14.000Z","size":99,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-14T13:51:15.577Z","etag":null,"topics":["data-format","json-alternative","legacy","legacy-php","llm","php","php-serialize","php-toon","php8","serialization","token-optimization","toon","toon-php"],"latest_commit_sha":null,"homepage":"https://packagist.org/packages/iamgerwin/toon-php","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iamgerwin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"Gerwin"}},"created_at":"2025-11-09T02:44:25.000Z","updated_at":"2025-12-02T16:39:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/iamgerwin/toon-php","commit_stats":null,"previous_names":["iamgerwin/toon-php"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/iamgerwin/toon-php","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamgerwin%2Ftoon-php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamgerwin%2Ftoon-php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamgerwin%2Ftoon-php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamgerwin%2Ftoon-php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iamgerwin","download_url":"https://codeload.github.com/iamgerwin/toon-php/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamgerwin%2Ftoon-php/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28747308,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T05:12:38.112Z","status":"ssl_error","status_checked_at":"2026-01-25T05:04:50.338Z","response_time":113,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-format","json-alternative","legacy","legacy-php","llm","php","php-serialize","php-toon","php8","serialization","token-optimization","toon","toon-php"],"created_at":"2025-12-13T01:03:32.689Z","updated_at":"2026-01-25T07:03:44.496Z","avatar_url":"https://github.com/iamgerwin.png","language":"PHP","readme":"# TOON PHP\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/iamgerwin/toon-php.svg?style=flat-square)](https://packagist.org/packages/iamgerwin/toon-php)\n[![Tests](https://img.shields.io/github/actions/workflow/status/iamgerwin/toon-php/run-tests.yml?branch=main\u0026label=tests\u0026style=flat-square)](https://github.com/iamgerwin/toon-php/actions/workflows/run-tests.yml)\n[![Total Downloads](https://img.shields.io/packagist/dt/iamgerwin/toon-php.svg?style=flat-square)](https://packagist.org/packages/iamgerwin/toon-php)\n\n\u003e **Stop wasting tokens. Start saving money.**\n\nA lightweight, blazing-fast **TOON (Token-Oriented Object Notation)** library for PHP that cuts your LLM API costs by **30-60%**. Because every token counts when you're building AI applications.\n\n## Why TOON?\n\nTraditional JSON is expensive for AI applications. Every `{`, `}`, `[`, `]`, and `\"` counts as a token. TOON eliminates this waste while maintaining perfect readability.\n\n```php\n// JSON: 168 characters, ~42 tokens\n{\"users\":[{\"name\":\"Alice\",\"age\":30,\"role\":\"admin\"},{\"name\":\"Bob\",\"age\":25,\"role\":\"user\"}]}\n\n// TOON: 89 characters, ~22 tokens (47% savings!)\nusers[2]{name,age,role}:\n  Alice,30,admin\n  Bob,25,user\n```\n\n## Real-World Performance\n\nBased on [official TOON benchmarks](https://github.com/toon-format/toon):\n\n| Use Case | JSON Tokens | TOON Tokens | Savings |\n|----------|-------------|-------------|---------|\n| E-commerce Orders | 3,245 | 2,170 | **33.1%** |\n| User Lists | 150 | 82 | **45.3%** |\n| Product Catalogs | 320 | 180 | **43.8%** |\n| Event Logs | 1,890 | 1,606 | **15.0%** |\n| Config Files | 2,456 | 1,687 | **31.3%** |\n\n### Cost Impact\n\nAt OpenAI's GPT-4 pricing ($0.03/1K tokens):\n- **1M API calls with 100 tokens each** = $3,000 (JSON) → **$1,500** (TOON)\n- **Annual savings**: **$1,500+** for moderate usage\n- **ROI**: Immediate (zero migration cost)\n\n## Installation\n\n```bash\ncomposer require iamgerwin/toon-php\n```\n\n**Requirements:**\n- PHP 8.1+ (v2.x - **Recommended**, Latest \u0026 Default)\n- PHP 7.0-8.0 (v1.x - Legacy Support)\n\n## Quick Start\n\n```php\nuse iamgerwin\\Toon\\Toon;\n\n// Simple encoding\n$user = [\n    'name' =\u003e 'Alice',\n    'email' =\u003e 'alice@example.com',\n    'active' =\u003e true,\n    'credits' =\u003e 1250\n];\n\n$toon = Toon::encode($user);\n// Output:\n//   name: Alice\n//   email: alice@example.com\n//   active: true\n//   credits: 1250\n\n// Decode back to PHP\n$decoded = Toon::decode($toon);\n\n// Compare with JSON\n$comparison = Toon::compare($user);\necho \"Token savings: {$comparison['savings_percent']}%\";\n// Token savings: 42.5%\n```\n\n## Powerful Features\n\n### 🎯 Tabular Format for Arrays\n\nPerfect for uniform datasets:\n\n```php\n$users = [\n    ['id' =\u003e 1, 'name' =\u003e 'Alice', 'role' =\u003e 'admin'],\n    ['id' =\u003e 2, 'name' =\u003e 'Bob', 'role' =\u003e 'user'],\n    ['id' =\u003e 3, 'name' =\u003e 'Charlie', 'role' =\u003e 'user'],\n];\n\necho Toon::tabular($users);\n// Output:\n// [3]{id,name,role}:\n//   1,Alice,admin\n//   2,Bob,user\n//   3,Charlie,user\n\n// vs JSON: {\"users\":[{\"id\":1,\"name\":\"Alice\"...}]}\n```\n\n**73.9% retrieval accuracy** vs 70.7% for JSON in LLM benchmarks ([source](https://github.com/toon-format/toon)).\n\n### ⚡ Multiple Encoding Modes\n\n```php\n$data = ['foo' =\u003e 'bar', 'items' =\u003e [1, 2, 3]];\n\n// Compact (minimal whitespace)\n$compact = Toon::compact($data);\n// foo: bar\n// items[3]: 1,2,3\n\n// Readable (4-space indentation)\n$readable = Toon::readable($data);\n//     foo: bar\n//     items[3]: 1,2,3\n\n// Custom options\nuse iamgerwin\\Toon\\EncodeOptions;\nuse iamgerwin\\Toon\\Enums\\ToonDelimiter;\n\n$custom = Toon::encode($data, new EncodeOptions(\n    indent: 2,\n    delimiter: ToonDelimiter::TAB,\n    preferTabular: true\n));\n```\n\n### 🔍 Token Analysis\n\n```php\n$data = ['large' =\u003e 'dataset', 'with' =\u003e 'many', 'fields' =\u003e true];\n\n$analysis = Toon::compare($data);\n/*\n[\n    'toon' =\u003e '  large: dataset...',\n    'json' =\u003e '{\"large\":\"dataset\"...}',\n    'toon_tokens' =\u003e 15,\n    'json_tokens' =\u003e 25,\n    'savings_percent' =\u003e 40.0\n]\n*/\n\n// Estimate tokens before sending to LLM\n$tokens = Toon::estimateTokens($toonString);\necho \"Estimated cost: $\" . ($tokens / 1000 * 0.03);\n```\n\n### 🎨 Complete Type Support\n\n```php\n// DateTime objects\n$data = [\n    'created_at' =\u003e new DateTime('2024-01-01 12:00:00'),\n    'updated_at' =\u003e new DateTime('2024-01-15 10:30:00')\n];\n$toon = Toon::encode($data);\n// created_at: 2024-01-01T12:00:00+00:00\n// updated_at: 2024-01-15T10:30:00+00:00\n\n// Enums (PHP 8.1+)\nenum Status: string {\n    case Active = 'active';\n    case Pending = 'pending';\n}\n\n$order = ['status' =\u003e Status::Active, 'amount' =\u003e 99.99];\n$toon = Toon::encode($order);\n// status: active\n// amount: 99.99\n\n// Nested structures\n$complex = [\n    'user' =\u003e [\n        'profile' =\u003e ['name' =\u003e 'Alice'],\n        'settings' =\u003e ['theme' =\u003e 'dark']\n    ]\n];\n// Full round-trip support!\n```\n\n## Helper Functions\n\n```php\n// Global helpers for convenience\ntoon($data);                    // Encode with defaults\ntoon_decode($string);           // Decode TOON string\ntoon_compact($data);            // Compact format\ntoon_readable($data);           // Readable format\ntoon_tabular($array);           // Tabular for uniform arrays\ntoon_compare($data);            // Compare with JSON\ntoon_estimate_tokens($string);  // Estimate token count\n```\n\n## When to Use TOON\n\n### ✅ Perfect For:\n\n- **LLM API calls** (ChatGPT, Claude, Gemini)\n- **AI agent communication**\n- **Prompt engineering** (system prompts, context)\n- **Chatbot memory** (conversation history)\n- **Training data** (uniform datasets)\n- **Cost-sensitive applications**\n\n### ⚠️ Consider JSON When:\n\n- Building public REST APIs\n- Need universal ecosystem support\n- Working with deeply nested structures (\u003e5 levels)\n\n## Benchmarks\n\nIndependent tests show TOON's advantages:\n\n### Token Efficiency\n- **Average savings**: 30-60% vs JSON\n- **Best case**: 62% reduction (flat tabular data)\n- **Worst case**: 15% reduction (semi-structured data)\n\n### LLM Retrieval Accuracy\nTested across 209 questions on 4 LLM models:\n- **TOON**: 73.9% accuracy | 2,744 tokens\n- **JSON (compact)**: 70.7% accuracy | 3,081 tokens\n- **JSON (formatted)**: 69.7% accuracy | 4,545 tokens\n\nTOON achieves **+3.2% better accuracy** while using **39.6% fewer tokens** ([source](https://github.com/toon-format/toon)).\n\n### Processing Speed\n- **Faster tokenization** (less overhead)\n- **Improved throughput** (smaller payloads)\n- **Better context utilization** (more data in context window)\n\n## Advanced Usage\n\n### Strict vs Lenient Decoding\n\n```php\nuse iamgerwin\\Toon\\DecodeOptions;\n\n// Strict mode (default) - validates structure\n$strict = Toon::decode($toon, DecodeOptions::strict());\n\n// Lenient mode - forgiving parsing\n$lenient = Toon::decode($toon, DecodeOptions::lenient());\n```\n\n### Custom Delimiters\n\n```php\nuse iamgerwin\\Toon\\{EncodeOptions, Enums\\ToonDelimiter};\n\n// Use tabs instead of commas\n$options = new EncodeOptions(delimiter: ToonDelimiter::TAB);\n$toon = Toon::encode($data, $options);\n// [3]: value1\tvalue2\tvalue3\n\n// Use pipes\n$options = new EncodeOptions(delimiter: ToonDelimiter::PIPE);\n$toon = Toon::encode($data, $options);\n// [3]: value1|value2|value3\n```\n\n## Quality Assurance\n\nThis package maintains the highest quality standards:\n\n- ✅ **PHPStan Level 6** (strict static analysis)\n- ✅ **PSR-12** code style compliance\n- ✅ **100% test coverage** (29 tests, 63 assertions)\n- ✅ **Zero dependencies** (pure PHP)\n- ✅ **Continuous Integration** (GitHub Actions)\n- ✅ **Multi-version testing** (PHP 8.1-8.4)\n\n```bash\ncomposer test      # Run Pest test suite\ncomposer analyse   # PHPStan level 6 analysis\ncomposer format    # Fix code style with Pint\n```\n\n## Real-World Example\n\n```php\n// Building a chatbot with conversation history\n$history = [\n    ['role' =\u003e 'system', 'content' =\u003e 'You are a helpful assistant'],\n    ['role' =\u003e 'user', 'content' =\u003e 'What is TOON?'],\n    ['role' =\u003e 'assistant', 'content' =\u003e 'TOON is a token-efficient format...'],\n    ['role' =\u003e 'user', 'content' =\u003e 'How much can I save?'],\n];\n\n// JSON: ~280 tokens = $0.0084 per call\n$json = json_encode($history);\n\n// TOON: ~165 tokens = $0.00495 per call (41% savings!)\n$toon = Toon::tabular($history);\n\n// Send to OpenAI\n$response = $openai-\u003echat()-\u003ecreate([\n    'model' =\u003e 'gpt-4',\n    'messages' =\u003e Toon::decode($toon)  // Convert back for API\n]);\n\n// Annual savings with 100K calls: $345\n```\n\n## Migration from JSON\n\nZero-effort migration:\n\n```php\n// Before (JSON)\n$json = json_encode($data);\nsendToLLM($json);\n$result = json_decode($response);\n\n// After (TOON) - just swap the functions!\n$toon = toon($data);\nsendToLLM($toon);\n$result = toon_decode($response);\n\n// Measure your savings\n$comparison = toon_compare($data);\necho \"You're now saving {$comparison['savings_percent']}% on tokens!\";\n```\n\n## Contributing\n\nContributions are welcome! This package follows:\n- [PSR-12](https://www.php-fig.org/psr/psr-12/) coding standards\n- [Semantic Versioning](https://semver.org/)\n- [Conventional Commits](https://www.conventionalcommits.org/)\n\n## Versioning\n\nThis library follows [Semantic Versioning](https://semver.org/) with separate branches for different PHP versions:\n\n- **v2.x** ([main branch](https://github.com/iamgerwin/toon-php)): PHP 8.1-8.4 with modern features - **Latest \u0026 Default**\n- **v1.x** ([legacy branch](https://github.com/iamgerwin/toon-php/tree/legacy)): PHP 7.0-8.0 compatibility - **Legacy Support**\n\n**Version 2.x is the recommended and default version** for new projects. Composer will automatically select v2.x for PHP 8.1+ installations and v1.x for PHP 7.0-8.0 installations.\n\n### Branches\n\n- **main** → v2.x (PHP 8.1+) - Active development, latest features\n- **legacy** → v1.x (PHP 7.0-8.0) - Bug fixes only, no new features\n\n### Installation by PHP Version\n\n```bash\n# PHP 8.1+ (will install v2.x automatically)\ncomposer require iamgerwin/toon-php\n\n# PHP 7.0-8.0 (will install v1.x automatically)\ncomposer require iamgerwin/toon-php\n\n# Force specific version\ncomposer require iamgerwin/toon-php:^2.0  # Latest features (PHP 8.1+)\ncomposer require iamgerwin/toon-php:^1.0  # Legacy support (PHP 7.0-8.0)\n```\n\n### Feature Differences\n\n| Feature | v2.x (PHP 8.1+) | v1.x (PHP 7.0-8.0) |\n|---------|-----------------|---------------------|\n| TOON Encoding/Decoding | ✅ | ✅ |\n| DateTime Support | ✅ | ✅ |\n| Enum Support | ✅ | ❌ (PHP 8.1+ only) |\n| Tabular Format | ✅ | ✅ |\n| Helper Functions | ✅ | ✅ |\n| PHPStan Analysis | Level 6 | Level 6 |\n| Test Coverage | 29 tests | 32 tests |\n\n## License\n\nMIT License - see [LICENSE.md](LICENSE.md)\n\n## Credits\n\n- Built with ❤️ for the PHP and AI community\n- TOON format: [toon-format/toon](https://github.com/toon-format/toon)\n- Inspired by the need to make AI more accessible through cost reduction\n\n---\n\n**Stop paying for redundant tokens. Start using TOON PHP.**\n\n[Get Started](#installation) | [View Benchmarks](#benchmarks) | [See Examples](#quick-start)\n","funding_links":["https://github.com/sponsors/Gerwin"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiamgerwin%2Ftoon-php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiamgerwin%2Ftoon-php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiamgerwin%2Ftoon-php/lists"}