Toon Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require sbsaga/toon
   

   Publish the config (if needed):

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

2. First Conversion:

   use Sbsaga\Toon\Facades\Toon;
   
   $data = [
       'user' => ['name' => 'John', 'age' => 30],
       'preferences' => ['theme' => 'dark', 'notifications' => true]
   ];
   
   // Convert to TOON
   $toonString = Toon::encode($data);
   // Output: `user.name=John;user.age=30;preferences.theme=dark;preferences.notifications=1`
   
   // Convert back to array
   $decoded = Toon::decode($toonString);
   

3. First Use Case:

   • AI Prompt Optimization: Replace verbose JSON in LLM calls with TOON to reduce token usage.

     $prompt = "User data: " . Toon::encode($userData);
     $response = $openAI->complete($prompt);
     

Implementation Patterns

Core Workflows

1. Data Serialization for AI:

   • Use Case: Passing structured data to LLMs (e.g., chatbots, assistants).
   • Pattern:

     $context = [
         'user' => ['role' => 'admin', 'permissions' => ['create', 'edit']],
         'query' => 'List all active orders'
     ];
     $optimizedPrompt = "Context: " . Toon::encode($context) . "\nQuery: {$context['query']}";
     

2. URL-Friendly Data Transport:

   • Use Case: Embedding data in URLs (e.g., deep links, shareable filters).
   • Pattern:

     $filters = ['status' => 'active', 'limit' => 10];
     $url = route('search', ['data' => Toon::encode($filters)]);
     // Decode in controller: Toon::decode(request('data'))
     

3. Log Compaction:

   • Use Case: Storing large request/response payloads in logs without bloating storage.
   • Pattern:

     $logEntry = [
         'event' => 'order_created',
         'payload' => Toon::encode($orderData),
         'metadata' => ['user_id' => 123]
     ];
     

4. Cache Key Generation:

   • Use Case: Creating compact cache keys for complex data.
   • Pattern:

     $cacheKey = "user_{$userId}_" . Toon::encode(['prefs' => $prefs, 'last_active' => now()]);
     cache()->put($cacheKey, $userData, now()->addHours(1));
     

Integration Tips

• Middleware for TOON Decoding: Decode TOON-encoded data in middleware for routes expecting compact payloads:

  public function handle(Request $request, Closure $next) {
      if ($request->has('toon_data')) {
          $request->merge(['data' => Toon::decode($request->toon_data)]);
      }
      return $next($request);
  }
  

• Form Data Handling: Use TOON to serialize form inputs for submission:

  // Blade form
  <input type="hidden" name="filters" value="{{ Toon::encode($defaultFilters) }}">
  
  // Controller
  $filters = Toon::decode(request('filters'));
  

• API Response Compression: Offer TOON as an alternative to JSON in API responses:

  return response()->json([
      'data' => Toon::encode($data),
      'format' => 'toon'
  ]);
  

Gotchas and Tips

Pitfalls

1. Nested Arrays/Objects:

   • TOON flattens nested structures with dot notation (e.g., user.address.city). Ensure your use case handles this explicitly.
   • Fix: Use Toon::encode($data, ['nested_delimiter' => '|']) for custom separators.

2. Boolean/Null Values:

   • TOON encodes true as 1, false as 0, and null as empty. Validate decoded data if strict typing is required.
   • Tip: Add a post-decode validation layer:

     $data = Toon::decode($toonString);
     $data = array_map(function($value) {
         return $value === '1' ? true : ($value === '0' ? false : $value);
     }, $data);
     

3. Special Characters:

   • TOON escapes ;, =, and newlines by default. If working with user-generated data, ensure no malformed input breaks parsing.
   • Debugging: Use Toon::decode($toonString, ['strict' => false]) to catch malformed input gracefully.

4. Token Efficiency Trade-offs:

   • TOON is more compact than JSON but may not always be the most efficient for very large datasets. Benchmark for your specific use case.
   • Tip: Compare token counts:

     $jsonLength = strlen(json_encode($data));
     $toonLength = strlen(Toon::encode($data));
     

5. Laravel Collections:

   • TOON does not natively support Laravel Collections. Convert to arrays first:

     $toon = Toon::encode($collection->toArray());
     

Debugging

• Validation Errors: If Toon::decode() fails, check for:

  • Unescaped special characters (;, =).
  • Malformed key-value pairs (e.g., missing =).
  • Use Toon::decode($toonString, ['debug' => true]) for verbose error messages.

• Unexpected Output: TOON preserves array order. If order matters, ensure consistency in encoding/decoding:

  $encoded = Toon::encode($array, ['preserve_order' => true]);
  

Extension Points

1. Custom Encoders/Decoders: Extend the package by creating custom encoders for domain-specific data:

   Toon::extend('user', function($value) {
       return "user_{$value['id']}_{$value['role']}";
   });
   

2. TOON Middleware: Create reusable middleware for TOON-based request/response handling:

   class ToonRequestMiddleware {
       public function handle($request, Closure $next) {
           if ($request->has('toon')) {
               $request->merge(['data' => Toon::decode($request->toon)]);
           }
           return $next($request);
       }
   }
   

3. TOON Storage: Integrate with Laravel Filesystem for TOON-based storage:

   $disk = Storage::disk('toon');
   $disk->put('user_123_prefs', Toon::encode($prefs));
   

4. TOON Query Builder: Use TOON to serialize query parameters for complex searches:

   $queryParams = ['status' => 'active', 'tags' => ['urgent', 'high-priority']];
   $url = route('search', ['q' => Toon::encode($queryParams)]);
   

Configuration Quirks

• Default Delimiters: The package uses ; for pairs and = for key-value separation. Override in config:

  'delimiters' => [
      'pair' => '|',
      'key_value' => ':'
  ],
  

• Reserved Characters: TOON escapes ;, =, and \n. Add more via config:

  'reserved_chars' => [';', '=', '\n', ','],
  

Performance Tips

• Batch Processing: For large datasets, process in chunks to avoid memory issues:

  $chunkSize = 1000;
  foreach (array_chunk($largeArray, $chunkSize) as $chunk) {
      $toon = Toon::encode($chunk);
      // Process $toon
  }
  

• Caching: Cache frequently encoded/decoded TOON strings:

  $cacheKey = "toon_{$userId}";
  if (!cache()->has($cacheKey)) {
      cache()->put($cacheKey, Toon::encode($userData), now()->addHours(1));
  }