Skip to content

quickstart.md

Latest commit

 

History

History
213 lines (151 loc) · 5.08 KB

quickstart.md

File metadata and controls

213 lines (151 loc) · 5.08 KB
Raw

Quickstart

Get Started in 60 Seconds — Install, Encode, Use

This page helps you get from zero to production-ready usage quickly.

Who This Is For

Use TOON when you want structured data that is:

  • smaller and easier to read than JSON
  • still reversible back into arrays with decode()
  • useful for prompts, logs, fixtures, and internal review flows

If your use case is external API transport, JSON should still be your default.

Install

composer require sbsaga/toon

Laravel package discovery registers provider and facade automatically.

Optional: publish config.

php artisan vendor:publish --provider="Sbsaga\Toon\ToonServiceProvider" --tag=config

First Success in 2 Minutes

Drop this in a route or tinker session:

use Illuminate\Support\Facades\Route;
use Sbsaga\Toon\Facades\Toon;

Route::get('/toon-demo', function () {
    $payload = [
        'project' => 'TOON',
        'users' => [
            ['id' => 1, 'name' => 'Alice', 'active' => true],
            ['id' => 2, 'name' => 'Bob', 'active' => false],
        ],
    ];

    $encoded = Toon::encode($payload);
    $decoded = Toon::decode($encoded);

    return response()->json([
        'toon' => $encoded,
        'decoded' => $decoded,
    ]);
});

What the Output Means

Typical encoded output:

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

How to read it:

  • project: TOON is a simple key/value pair
  • users: starts a nested block
  • items[2]{...} is a table with 2 rows and named columns
  • each row contains the values for that column order

Core API You Need First

Encode/Decode Pipeline — PHP Array → TOON String → PHP Array 

use Sbsaga\Toon\Facades\Toon;

$toon = Toon::encode($payload);          // array/json/scalar -> TOON string
$data = Toon::decode($toon);             // TOON string -> array
$stats = Toon::estimateTokens($toon);    // quick rough token estimate
$diff = Toon::diff($payload);            // JSON-vs-TOON size comparison

Global helpers are also available:

$toon = toon_encode($payload);
$data = toon_decode($toon);
$diff = toon_diff($payload);

Safe Defaults and Compatibility

Default mode is legacy, which keeps old behavior safer for existing users.

// config/toon.php
'compatibility_mode' => 'legacy',

Use modern for new projects or controlled migrations:

// config/toon.php
'compatibility_mode' => 'modern',

Production Pattern: Redact Before Encoding

Use replacers to remove sensitive fields before TOON encoding.

use Sbsaga\Toon\Facades\Toon;

$safeToon = Toon::encodeWith($payload, function (array $path, string|int|null $key, mixed $value) {
    if (in_array($key, ['password', 'token', 'api_key'], true)) {
        return Toon::skip();
    }

    if ($key === 'email') {
        return '[redacted]';
    }

    return $value;
});

Helper version:

$safeToon = toon_encode_with($payload, function (array $path, string|int|null $key, mixed $value) {
    return $key === 'debug' ? \Sbsaga\Toon\Toon::skip() : $value;
});

Production Pattern: Stream-Oriented Usage

If you want line-based processing:

use Sbsaga\Toon\Facades\Toon;

$lines = Toon::encodeLines($payload);        // Generator<string>
$decoded = Toon::decodeFromLines($lines);    // array

Helper:

$lines = toon_encode_lines($payload); // array of lines

CLI Usage for Teams and Pipelines

Basic encode/decode:

php artisan toon:convert storage/app/payload.json --encode
php artisan toon:convert storage/app/payload.toon --decode --pretty

Explicit direction and stats:

php artisan toon:convert storage/app/payload.data --from=json --to=toon --stats

One-off runtime overrides:

php artisan toon:convert storage/app/payload.json --encode --mode=modern --delimiter=pipe

Strict validation for decode:

php artisan toon:convert storage/app/payload.toon --decode --strict

Production Readiness Checklist

  1. Keep compatibility_mode=legacy for initial upgrade rollout.
  2. Add at least one encode/decode round-trip test for your critical payloads.
  3. Add a replacer for sensitive fields before logs/prompts.
  4. Enable strict decoding where malformed input must fail fast.
  5. Roll modern mode only after downstream consumers are verified.

Common Mistakes to Avoid

  • Using TOON as a direct replacement for public API JSON payloads
  • Enabling modern mode in production without contract checks
  • Logging raw sensitive payloads without replacer redaction
  • Assuming token savings for very small payloads without measuring

Next Guides