Download the PHP package digitalcorehub/laravel-toon without Composer

Laravel Toon

A lightweight Laravel package that converts standard JSON into TOON format - a human-readable, ultra-minimal, line-based data format.

🇹🇷 Türkçe Dokümantasyon için tıklayın

Features

• ✅ Convert JSON to TOON format
• ✅ Ultra-minimal, human-readable output
• ✅ Preserves JSON key ordering
• ✅ Supports nested arrays and objects
• ✅ CLI command for file conversion
• ✅ Laravel Facade support
• ✅ Full test coverage

Installation

Install the package via Composer:

The package will automatically register its service provider and facade.

Requirements

• PHP 8.3 or higher
• Laravel 10.x, 11.x, or 12.x

Usage

Helper Functions

The package provides global helper functions for easy access:

Using the Facade

Fluent Interface

The package supports a fluent builder-style API:

The fluent interface is especially useful for method chaining and readability.

Encode from JSON String

Arrays with Objects

Nested Structures

Blade Directive

Use the @toon() directive in your Blade templates to display TOON output:

The directive automatically:

• Encodes the data to TOON format
• Wraps it in a <pre> tag
• Escapes HTML for safe output

Example:

Output:

Logging Support

Log data in TOON format using the Log::toon() macro:

The macro encodes your data to TOON format and logs it through Laravel's logging system.

Console Styling

Get colored TOON output for console/terminal:

Syntax Highlighting:

• Keys: Yellow
• Strings: Green
• Numbers: Blue
• Booleans: Magenta
• Brackets: Cyan

Laravel Debugbar Integration

If you have Laravel Debugbar installed, the package automatically registers a TOON panel that shows:

• Recent encode/decode operations
• Performance timing (duration in milliseconds)
• Metadata (key count, row count, line count)
• Input/output preview

The integration is automatic - no configuration needed. If Debugbar is not installed, the package works normally without it.

Note: Debugbar integration is optional and does not affect package functionality if Debugbar is not installed.

Streaming Encoder

For large JSON files, use the streaming encoder to avoid loading everything into memory:

The streaming encoder:

• Reads JSON file efficiently
• Writes TOON output progressively
• Reduces memory usage for large files
• Supports both local paths and Laravel Storage disks

Lazy Encoder

Get TOON output line by line using a generator:

Lazy encoder is perfect for:

• Large datasets
• Real-time output
• Memory-constrained environments
• Terminal/console output

Compact Mode

Enable compact mode for smaller, faster output:

Compact mode:

• Removes extra whitespace
• Uses minimal separators (no spaces after commas)
• Produces smaller files
• Faster encoding/decoding

Example:

Benchmarking

Measure performance with the benchmark command:

The benchmark shows:

• Encode speed (milliseconds)
• Decode speed (milliseconds)
• Memory usage (peak and used)
• Total rows processed
• Total keys processed
• File size comparison

Example Output:

Performance Best Practices

1. Use streaming for large files:

2. Enable compact mode in production:

3. Use lazy encoder for real-time output:

4. Monitor performance:

Decode TOON to Array

Decode Multiple Rows

Decode Nested Structures

Error Handling

The decode method throws InvalidToonFormatException for invalid TOON formats:

Common errors include:

• Missing semicolons in keys line (with line numbers)
• Mismatched key/value counts (with line numbers)
• Unclosed brackets { or } (with descriptive messages)
• Invalid array block formats

Example Error Messages:

Using Dependency Injection

CLI Commands

Encode: JSON → TOON

Convert JSON files to TOON format using the Artisan command:

Options:

• --preview or -p: Show colored preview of the output

Example:

Decode: TOON → JSON

Convert TOON files to JSON format using the Artisan command:

Options:

• --preview or -p: Show colored preview of the input

Example:

Error Handling:

If the TOON file has invalid format, the command will display an error message:

Benchmark: Performance Testing

Measure TOON encode/decode performance:

Options:

• file: Optional path to JSON file. If not provided, uses first file from tests/bench/ directory.

Example:

The benchmark command displays:

• Encode speed (milliseconds)
• Decode speed (milliseconds)
• Memory usage (peak and used)
• Total rows and keys processed
• File size comparison (TOON vs JSON)

Store: Save TOON to Laravel Storage

Save TOON files using Laravel Storage:

Options:

• --disk: The storage disk to use (default: from config toon.storage.default_disk)

Example:

File Storage & Download

Storing TOON Files

Save TOON data to Laravel Storage:

Features:

• Automatically adds .toon extension if missing
• Creates directories automatically
• Uses default directory from config (toon.storage.default_directory)
• Returns full saved file path

Configuration:

Downloading TOON Files

Download TOON data as a file response:

Response Headers:

• Content-Type: text/toon
• Content-Disposition: attachment; filename="users.toon"

The download method:

• Automatically adds .toon extension if missing
• Streams response efficiently
• Sets proper headers for file download

API Response Macro

Return TOON format in API responses:

Response Headers:

• Content-Type: text/toon

Example Route:

The response()->toon() macro:

• Encodes data to TOON format
• Sets Content-Type: text/toon header
• Returns standard Laravel response

File Structure: After storing files, they will be located at:

TOON Format Rules

The TOON format follows these rules:

1. Objects: Keys are listed on the first line, followed by values on the next line

2. Arrays: Display with size indicator arrayName[count]{...}

3. Minimal Syntax: Removes unnecessary {}, [], commas, and quotes where possible

4. Order Preservation: Maintains the original JSON key ordering

5. Nested Support: Fully supports nested arrays and objects

Configuration

Publishing the Configuration File

To customize the package settings, you need to publish the configuration file to your Laravel application:

This command will create a config/toon.php file in your Laravel project's config directory.

Configuration File Location

After publishing, the configuration file will be located at:

Configuration Options

The published configuration file contains the following options:

Using Configuration Values

You can access configuration values in your code:

Note: The configuration file is optional. If you don't publish it, the package will use default values.

Testing

Run the test suite:

Examples

Example 1: Simple Object

Input (JSON):

Output (TOON):

Example 2: Array of Objects

Input (JSON):

Output (TOON):

Example 3: Complex Nested Structure

Input (JSON):

Output (TOON):

Version

Current version: v0.6.0

This version includes:

• ✅ JSON → TOON encoding
• ✅ TOON → JSON decoding
• ✅ File Storage - Save TOON files using Laravel Storage (store)
• ✅ Download Support - Download TOON files as HTTP responses (download)
• ✅ API Response Macro - response()->toon() for API endpoints
• ✅ Store Command - php artisan toon:store for CLI file storage
• ✅ Streaming encoder for large files (encodeStream)
• ✅ Lazy encoder for line-by-line output (lazy)
• ✅ Benchmark command (php artisan toon:bench)
• ✅ Compact mode for smaller, faster output
• ✅ Experimental streaming decode (decodeStream)
• ✅ CLI commands (encode, decode, store) with colored preview
• ✅ Global helper functions (toon_encode, toon_decode)
• ✅ Fluent interface (fromJson, fromArray, fromToon)
• ✅ Blade directive @toon() for easy template integration
• ✅ Laravel Debugbar integration (auto-detected)
• ✅ Log::toon() macro for logging support
• ✅ Console styling with syntax highlighting
• ✅ Configurable formatting (indentation, separators, line breaks)
• ✅ Improved exception messages with line numbers
• ✅ Facade and DI support
• ✅ Comprehensive test coverage
• ✅ Error handling with custom exceptions

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

The MIT License (MIT). Please see License File for more information.

Credits

Developed by DigitalCoreHub

Made with ❤️ for the Laravel community