PHPackages                             mischasigtermans/laravel-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. mischasigtermans/laravel-toon

ActiveLibrary[Parsing & Serialization](/categories/parsing)

mischasigtermans/laravel-toon
=============================

Token-Optimized Object Notation encoder/decoder for Laravel with intelligent nested object handling

v1.1.0(1mo ago)13113.1k↑16.3%6[1 PRs](https://github.com/mischasigtermans/laravel-toon/pulls)MITPHPPHP ^8.2CI passing

Since Dec 7Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/mischasigtermans/laravel-toon)[ Packagist](https://packagist.org/packages/mischasigtermans/laravel-toon)[ RSS](/packages/mischasigtermans-laravel-toon/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (6)Dependencies (12)Versions (10)Used By (0)

Laravel TOON
============

[](#laravel-toon)

[![Latest Version on Packagist](https://camo.githubusercontent.com/e4f2619a07429776203fa90d81219c5878f5a3a59142b10256e9f3bcd4d2f5ce/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d69736368617369677465726d616e732f6c61726176656c2d746f6f6e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/mischasigtermans/laravel-toon)[![Total Downloads](https://camo.githubusercontent.com/3307d21acacd2b05c8736aecdd8aee61407ab0da5e237f3533d51cbb81cf2613/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d69736368617369677465726d616e732f6c61726176656c2d746f6f6e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/mischasigtermans/laravel-toon)

The most complete [TOON](https://toonformat.dev/) implementation for Laravel, and the only one with full [TOON v3.0 specification](https://github.com/toon-format/spec/blob/main/SPEC.md) compliance. Listed as [official Laravel implementation](https://toonformat.dev/ecosystem/implementations.html).

TOON (Token-Optimized Object Notation) is a compact, YAML-like format designed to reduce token usage when sending data to LLMs. This package achieves **~50% token reduction** compared to JSON while maintaining full round-trip fidelity, backed by 470 tests.

Installation
------------

[](#installation)

```
composer require mischasigtermans/laravel-toon
```

Quick Start
-----------

[](#quick-start)

```
use MischaSigtermans\Toon\Facades\Toon;

$data = [
    'users' => [
        ['id' => 1, 'name' => 'Alice', 'active' => true],
        ['id' => 2, 'name' => 'Bob', 'active' => false],
    ],
];

// Encode to TOON
$toon = Toon::encode($data);

// Decode back to array
$original = Toon::decode($toon);
```

**Output:**

```
users[2]{id,name,active}:
  1,Alice,true
  2,Bob,false

```

### Global Helper Functions

[](#global-helper-functions)

For convenience, global helper functions are available:

```
// Encode to TOON
$toon = toon_encode($data);

// Decode back to array
$original = toon_decode($toon);
```

### Collection Macro: `toToon`

[](#collection-macro-totoon)

You can convert any Laravel collection directly to TOON format with the built-in `toToon` macro:

```
$collection = collect([
    ['id' => 1, 'name' => 'Alice'],
    ['id' => 2, 'name' => 'Bob'],
]);
$toon = $collection->toToon();
```

**Output:**

```
items[2]{id,name}:
  1,Alice
  2,Bob

```

### Eloquent Model: `toToon`

[](#eloquent-model-totoon)

Eloquent models have a `toToon` method, similar to `toJson` and `toArray`:

```
$user = User::find(1);
$toon = $user->toToon();
```

Why TOON?
---------

[](#why-toon)

When building MCP servers or LLM-powered applications, every token counts. JSON's verbosity wastes context window space with repeated keys and structural characters.

**JSON (201 bytes):**

```
{"users":[{"id":1,"name":"Alice","role":"admin"},{"id":2,"name":"Bob","role":"user"},{"id":3,"name":"Carol","role":"user"}]}
```

**TOON (62 bytes) - 69% smaller:**

```
users[3]{id,name,role}:
  1,Alice,admin
  2,Bob,user
  3,Carol,user

```

Benchmarks
----------

[](#benchmarks)

For a typical paginated API response (50 records):

- **JSON**: ~7,597 tokens
- **TOON**: ~3,586 tokens
- **Saved**: ~4,000 tokens per request

Real-world benchmarks from a production application with 17,000+ records:

Data TypeJSONTOONSavings50 records30,389 bytes14,343 bytes**53%**100 records60,856 bytes28,498 bytes**53%**500 records303,549 bytes140,154 bytes**54%**1,000 records604,408 bytes277,614 bytes**54%**Features
--------

[](#features)

### Tabular Format

[](#tabular-format)

Arrays of uniform objects with primitive values are encoded as compact tables:

```
$data = [
    ['id' => 1, 'name' => 'Alice', 'role' => 'admin'],
    ['id' => 2, 'name' => 'Bob', 'role' => 'user'],
];

$toon = Toon::encode($data);
// [2]{id,name,role}:
//   1,Alice,admin
//   2,Bob,user
```

### List Format for Nested Objects

[](#list-format-for-nested-objects)

Arrays containing objects with nested properties use list format for clarity:

```
$data = [
    ['id' => 1, 'author' => ['name' => 'Jane', 'email' => 'jane@example.com']],
    ['id' => 2, 'author' => ['name' => 'John', 'email' => 'john@example.com']],
];

$toon = Toon::encode($data);
// [2]:
//   - id: 1
//     author:
//       name: Jane
//       email: jane@example.com
//   - id: 2
//     author:
//       name: John
//       email: john@example.com

$decoded = Toon::decode($toon);
// Returns original nested structure
```

### Type Preservation

[](#type-preservation)

All scalar types are preserved through encode/decode:

```
$data = [
    'count' => 42,
    'price' => 19.99,
    'active' => true,
    'deleted' => false,
    'notes' => null,
];

$decoded = Toon::decode(Toon::encode($data));
// Types are preserved: int, float, bool, null
```

### String Quoting (Spec-Compliant)

[](#string-quoting-spec-compliant)

Strings containing special characters are automatically quoted per the TOON spec:

```
$data = ['message' => 'Hello, World: How are you?'];
$toon = Toon::encode($data);
// message: "Hello, World: How are you?"

$data = ['text' => "Line 1\nLine 2"];
$toon = Toon::encode($data);
// text: "Line 1\nLine 2"
```

Safe strings (alphanumeric, underscores, dots) remain unquoted for minimal overhead.

Configuration
-------------

[](#configuration)

Publish the config file:

```
php artisan vendor:publish --tag=toon-config
```

### Basic Options

[](#basic-options)

```
// config/toon.php
return [
    // Arrays with fewer items use regular object format instead of tables
    'min_rows_for_table' => 2,

    // Delimiter for array values: ',' (default), '\t' (tab), or '|' (pipe)
    'delimiter' => ',',

    // Strict mode for decoding (throws on malformed input)
    'strict' => true,
];
```

### Token-Saving Options

[](#token-saving-options)

```
return [
    // Omit values to save tokens: 'null', 'empty', 'false', or 'all'
    'omit' => ['null', 'empty'],

    // Always skip these keys
    'omit_keys' => ['created_at', 'updated_at'],

    // Shorten verbose keys
    'key_aliases' => [
        'description' => 'desc',
        'organization_id' => 'org_id',
    ],
];
```

### Value Transformation

[](#value-transformation)

```
return [
    // Format dates (DateTime objects and ISO strings)
    'date_format' => 'Y-m-d',

    // Truncate long strings (adds ... suffix)
    'truncate_strings' => 100,

    // Limit decimal places for floats
    'number_precision' => 2,
];
```

Utility Methods
---------------

[](#utility-methods)

### Measure Savings

[](#measure-savings)

```
$data = User::with('roles')->get()->toArray();

$diff = Toon::diff($data);
// [
//     'json_chars' => 12500,
//     'toon_chars' => 5200,
//     'saved_chars' => 7300,
//     'savings_percent' => 58.4,
// ]
```

### Encode Specific Keys Only

[](#encode-specific-keys-only)

```
$users = User::all()->toArray();

// Only include id and name, exclude email, password, etc.
$toon = Toon::only($users, ['id', 'name']);
```

Use Cases
---------

[](#use-cases)

### MCP Servers

[](#mcp-servers)

Reduce token usage when returning data from MCP tool calls:

```
public function handle(): string
{
    $users = User::with('roles')->limit(100)->get();

    return Toon::encode([
        'count' => $users->count(),
        'users' => $users->toArray(),
    ]);
}
```

### LLM Context

[](#llm-context)

Pack more data into your context window:

```
$context = Toon::encode([
    'conversation' => $messages,
    'user_profile' => $user->toArray(),
    'recent_orders' => $orders->toArray(),
]);

$response = $llm->chat([
    ['role' => 'system', 'content' => "Context:\n{$context}"],
    ['role' => 'user', 'content' => $question],
]);
```

### API Responses

[](#api-responses)

Optional TOON responses for token-conscious clients:

```
public function index(Request $request)
{
    $data = Product::paginate()->toArray();

    if ($request->header('Accept') === 'application/toon') {
        return response(Toon::encode($data))
            ->header('Content-Type', 'application/toon');
    }

    return response()->json($data);
}
```

Spec Compliance
---------------

[](#spec-compliance)

This package implements the [TOON v3.0 specification](https://github.com/toon-format/spec/blob/main/SPEC.md) and passes the official specification test suite. Key compliance features:

- **String quoting**: Safe strings unquoted, special characters properly escaped (`\n`, `\r`, `\t`, `\"`, `\\`)
- **Delimiter support**: Comma (default), tab, and pipe delimiters
- **Tabular format**: Compact tables for arrays of primitive-only objects (`[N]{fields}:`)
- **List format**: Readable structure for arrays with nested objects (`[N]:` with `- field:` items)
- **Inline arrays**: Primitive arrays on single line (`key[N]: a,b,c`)
- **Strict mode**: Optional validation during decoding
- **Backward compatibility**: Decoder accepts legacy formats (backslash escaping, dot-notation columns)

Testing
-------

[](#testing)

```
composer test
```

The test suite includes 470 tests covering encoding, decoding, nested object handling, and official spec compliance fixtures.

Requirements
------------

[](#requirements)

- PHP 8.2+
- Laravel 10, 11, or 12

Credits
-------

[](#credits)

- [Mischa Sigtermans](https://github.com/mischasigtermans)

License
-------

[](#license)

MIT

###  Health Score

53

—

FairBetter than 97% of packages

Maintenance89

Actively maintained with recent releases

Popularity43

Moderate usage in the ecosystem

Community13

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 79.1% 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 ~21 days

Recently: every ~26 days

Total

6

Last Release

56d ago

Major Versions

v0.2.2 → v1.0.02026-01-20

### Community

Maintainers

![](https://www.gravatar.com/avatar/a002abdc851a76410e86443f04058710f9d32f82f31873f8c6544d2e881e79c6?d=identicon)[mischasigtermans](/maintainers/mischasigtermans)

---

Top Contributors

[![mischasigtermans](https://avatars.githubusercontent.com/u/22501510?v=4)](https://github.com/mischasigtermans "mischasigtermans (34 commits)")[![jimmypuckett](https://avatars.githubusercontent.com/u/3220069?v=4)](https://github.com/jimmypuckett "jimmypuckett (5 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (4 commits)")

---

Tags

aijson-alternativelaravelllmmcptoken-optimizationtoken-optimizertoonlaravelmcpaillmtoontoken-optimizationjson-alternative

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/mischasigtermans-laravel-toon/health.svg)

```
[![Health](https://phpackages.com/badges/mischasigtermans-laravel-toon/health.svg)](https://phpackages.com/packages/mischasigtermans-laravel-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)[php-mcp/laravel

Laravel SDK for building Model Context Protocol (MCP) servers - Seamlessly integrate MCP tools, resources, and prompts into Laravel applications

47283.1k1](/packages/php-mcp-laravel)[helgesverre/toon

Token-Oriented Object Notation - A compact data format for reducing token consumption when sending structured data to LLMs

11841.4k9](/packages/helgesverre-toon)[vizra/vizra-adk

Vizra Agent Development Kit - A comprehensive Laravel package for building intelligent AI agents.

29026.1k](/packages/vizra-vizra-adk)[neuron-core/neuron-laravel

Official Neuron AI Laravel SDK.

10710.0k](/packages/neuron-core-neuron-laravel)[vectorifyai/vectorify-laravel

Vectorify package for Laravel. The fastest way to ask AI about your data.

206.1k](/packages/vectorifyai-vectorify-laravel)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)