Json Builder Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require egeloen/json-builder
   

   Add to composer.json under require if not using Composer globally.

2. Basic Usage:

   use Ivory\Json\JsonBuilder;
   
   $builder = new JsonBuilder();
   $json = $builder->build(['key' => 'value']);
   echo $json; // Outputs: {"key":"value"}
   

3. First Use Case:

   • API Responses: Quickly construct JSON responses in Laravel controllers:

     return response()->json($builder->build([
         'status' => 'success',
         'data' => $user->toArray()
     ]));
     

Where to Look First

• Class Reference: Focus on Ivory\Json\JsonBuilder and its methods (build(), setEscaping(), etc.).
• README: Check for escaping control features (e.g., setEscaping(false) for raw output).
• Symfony PropertyAccess: Understand how nested objects/arrays are handled (e.g., $builder->build($object)).

Implementation Patterns

Core Workflows

1. Building JSON from Arrays/Objects:

   // Arrays
   $builder->build(['users' => [1, 2, 3]]);
   
   // Objects (via PropertyAccess)
   $builder->build((object)['name' => 'John']);
   

2. Escaping Control:

   • Disable escaping for raw JSON (e.g., HTML templates):

     $builder->setEscaping(false);
     $json = $builder->build('<script>alert("XSS")</script>');
     

   • Enable by default (safe for APIs):

     $builder->setEscaping(true); // Default
     

3. Integration with Laravel:

   • API Responses:

     return response()->json($builder->build($data), 200, [], JSON_PRETTY_PRINT);
     

   • Service Providers: Bind JsonBuilder to the container for reuse:

     $this->app->singleton(JsonBuilder::class, function ($app) {
         return new JsonBuilder();
     });
     

4. Nested Data Handling:

   • Automatically flattens objects/arrays:

     $builder->build([
         'user' => (object)['posts' => ['title' => 'Hello']]
     ]);
     // Output: {"user":{"posts":{"title":"Hello"}}}
     

Advanced Patterns

1. Custom Escaping Logic: Extend JsonBuilder to add custom escaping rules:

   class CustomJsonBuilder extends JsonBuilder {
       public function build($data) {
           $this->setEscaping(function ($value) {
               return str_replace('"', '\\"', $value);
           });
           return parent::build($data);
       }
   }
   

2. Batch Processing: Useful for generating multiple JSON responses:

   $builder = new JsonBuilder();
   $responses = collect($items)->map(fn ($item) => $builder->build($item));
   

3. Validation Integration: Combine with Laravel Validation for structured JSON:

   $validated = $request->validate(['name' => 'required|string']);
   return response()->json($builder->build($validated));
   

Gotchas and Tips

Pitfalls

1. Escaping Overhead:

   • Disabling escaping (setEscaping(false)) bypasses security checks. Use only for trusted data.
   • Example of unsafe usage:

     $builder->setEscaping(false);
     $json = $builder->build($userInput); // Risk of XSS if $userInput is untrusted.
     

2. Circular References:

   • Fails silently on circular references in objects/arrays. Use json_encode() as fallback:

     try {
         $json = $builder->build($data);
     } catch (\RuntimeException $e) {
         $json = json_encode($data);
     }
     

3. PropertyAccess Limitations:

   • Non-public properties require PropertyAccess configuration. Ensure your objects are accessible:

     $propertyAccessor = PropertyAccess::createPropertyAccessorBuilder()
         ->enableMagicCall()
         ->getPropertyAccessor();
     $builder->setPropertyAccessor($propertyAccessor);
     

Debugging Tips

1. Inspect Raw Data: Use var_dump() or dd() to verify input structure before building JSON:

   dd($builder->getData()); // Check data before serialization.
   

2. Error Handling: Wrap build() in try-catch for graceful fallbacks:

   try {
       $json = $builder->build($data);
   } catch (\Exception $e) {
       Log::error("JSON build failed: " . $e->getMessage());
       return response()->json(['error' => 'Invalid data'], 500);
   }
   

3. Performance:

   • Reuse JsonBuilder instances (e.g., as a singleton) to avoid reinitialization overhead.
   • Avoid deep nesting in input data for large payloads.

Extension Points

1. Custom Serializers: Implement Ivory\Json\Serializer\SerializerInterface to handle custom types:

   class DateTimeSerializer implements SerializerInterface {
       public function serialize($value) {
           return $value->format('Y-m-d');
       }
   }
   $builder->addSerializer(new DateTimeSerializer());
   

2. Event Listeners: Extend JsonBuilder to trigger events (e.g., pre/post-build hooks):

   $builder->addListener(function ($data) {
       $data['timestamp'] = now()->toIso8601String();
       return $data;
   });
   

3. Configuration:

   • Set default escaping globally via a service provider:

     $builder = new JsonBuilder();
     $builder->setEscaping(config('app.json_escaping', true));
     $this->app->singleton(JsonBuilder::class, fn() => $builder);