Download the PHP package abdelhamiderrahmouni/toon-php without Composer

Toon PHP

Toon PHP encodes PHP associative arrays and objects into the TOON format (Token‑Oriented Object Notation). It’s built first for PHP data structures—arrays and plain objects—and also works with JSON inputs by decoding them before encoding.

It favors:

• Inline arrays for primitives
• Tabular rows for uniform arrays of objects
• Safe string quoting to avoid ambiguity
• Customizable indentation, delimiters, and an optional array length marker

This makes structured PHP data easy for humans to scan while staying unambiguous for machines (and token‑efficient for LLMs).

Installation

Install via Composer (replace with your package name once published):

Quick Start (arrays and objects)

Output:

Works with plain objects too (stdClass, public props):

Options:

Output:

Working with JSON (optional)

If your data starts as JSON, decode it first, then pass the PHP value to encode(). Arrays/objects are the primary path; JSON is just another input source.

Reading from a file:

Notes:

• Using true (associative) is convenient, but objects (stdClass) also work — normalization handles both.
• Non-finite numbers and other PHP-specific values are normalized as described below.

Key Features

• Objects render as key: value pairs with indentation for nesting.

• Arrays:

  • Primitive arrays inline: tags:[3]: a,b,c

  • Array of objects with uniform keys and primitive values renders as a table:

  • Mixed arrays and complex structures fall back to list items:
• Safe string encoding: strings that look ambiguous (booleans, null, numeric-like, contain structural characters, etc.) are quoted and escaped.
• Custom delimiter for inline arrays/tabular rows: comma (default), tab, or pipe (or any string).
• Optional length marker # to prefix array lengths in headers: [#3].

Normalization Semantics

Toon PHP normalizes input into a JSON-like shape before encoding:

• Scalars:
  • null → null
  • bool, int, float preserved, with:
    • -0.0 canonicalized to 0
    • INF, -INF, NAN normalized to null
• DateTimeInterface → ISO 8601 string (DATE_ATOM)
• Stringable → cast to string
• JsonSerializable → jsonSerialize() result is normalized recursively
• Enums:
  • BackedEnum → backing value (then normalized)
  • UnitEnum → enum name
• Arrays:
  • List arrays (0..n-1 integer keys) are treated as arrays
  • Associative arrays are treated as objects (maps)
• Traversable → array via iterator_to_array
• Objects → associative arrays of public properties
• Unsupported types (resources, closures) → null

Note: PHP has no BigInt primitive; nothing special is needed here (unlike the TS version).

Output Rules and Examples

Objects

• Keys are unquoted if matching /^[A-Z_][\w.]*$/i; otherwise quoted.
• Empty objects render as key: on a line by itself.

Primitive Arrays (Inline)

• Header syntax: key:[length<delimiter-if-not-default>]
• A space separates the header and the joined values when non-empty.

Arrays of Arrays (Expanded List)

Arrays of Objects (Tabular)

Uniform keys and primitive values:

Otherwise, fall back:

Mixed Arrays

String and Key Encoding

• Strings are left unquoted only if “safe.” They are quoted if:
  • Empty or padded with whitespace
  • Equal to true, false, or null
  • Numeric-like (e.g., 42, -3.14, 1e-6, 05)
  • Contain :, quotes, backslashes, brackets/braces, control characters (\n, \r, \t)
  • Contain the active delimiter
  • Start with - (list marker)
• Strings are escaped for \\, ", newline, carriage return, and tab.
• Keys are unquoted when they match /^[A-Z_][\w.]*$/i, otherwise quoted.

API

• Namespace: Toon

Function

• function encode(mixed $input, ?EncodeOptions $options = null): string

  Encodes normalized input to the Toon format.

Options

• indent — spaces per indentation level
• delimiter — used for inline arrays and tabular rows (e.g., ",", "\t", "|")
• lengthMarker — '#' to render headers like [#N], or false to omit

Testing

This repo includes Pest tests that mirror the TypeScript behavior.

Run tests:

Differences from the TypeScript Version

• PHP-specific normalization:
  • DateTimeInterface → ISO string
  • Traversable, JsonSerializable, Stringable, and Enums → normalized as described
  • Objects → arrays/associative arrays
• No BigInt handling (not applicable to PHP)
• Arrays are identified as:
  • List arrays (0..n-1) → arrays
  • Associative arrays → objects

Credits

• Original inspiration and format: Toon by @johannschopplich

License

MIT