Json Pointer Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ergebnis/json-pointer
   

   Add to composer.json if using a monorepo or custom setup.

2. First Use Case: Navigate to a nested JSON value using RFC 6901-compliant pointers:

   use Ergebnis\Json\Pointer;
   
   $pointer = Pointer\ReferenceToken::fromString('/user/address/city');
   $value = $pointer->getValueFrom(json_decode($jsonString, true));
   

3. Key Classes:

   • ReferenceToken: Core class for pointer operations.
   • PointerException: Handle invalid pointers or missing keys.
   • PointerBuilder: For constructing pointers programmatically.

Where to Look First

• Documentation: RFC 6901 (standard reference).
• Tests: tests/ for edge cases.
• API Docs: Generated via phpDocumentor.

Implementation Patterns

Common Workflows

1. Pointer Creation:

   // From string (RFC 6901 format)
   $token = Pointer\ReferenceToken::fromString('/a/b/c');
   
   // From array (programmatic)
   $token = Pointer\PointerBuilder::create()->add('a')->add('b')->add('c')->build();
   

2. Value Extraction:

   $data = ['a' => ['b' => ['c' => 'value']]];
   $value = $token->getValueFrom($data); // Returns 'value'
   

3. Validation:

   if ($token->isValid()) {
       $value = $token->getValueFrom($data);
   }
   

4. Modification:

   $token->setValueOn($data, 'new_value'); // Mutates $data
   

Integration Tips

• Laravel Collections:

  use Illuminate\Support\Collection;
  
  $collection = collect($data);
  $value = $token->getValueFrom($collection->toArray());
  

• API Responses: Validate incoming JSON pointers in request payloads:

  $request->validate([
      'pointer' => ['required', 'string', function ($attribute, $value, $fail) {
          try {
              Pointer\ReferenceToken::fromString($value);
          } catch (PointerException $e) {
              $fail('Invalid JSON pointer.');
          }
      }]
  ]);
  

• Dynamic Pointers: Build pointers from user input or config:

  $path = config('dynamic.path');
  $token = Pointer\PointerBuilder::create()->add($path)->build();
  

Gotchas and Tips

Pitfalls

1. Invalid Pointers:

   • Empty strings or malformed paths (e.g., /a//b) throw PointerException.
   • Fix: Validate with try-catch or isValid() before use.

2. Non-Array Data:

   • Passing non-array JSON (e.g., strings, objects) to getValueFrom() may fail.
   • Fix: Cast to array first:

     $token->getValueFrom((array) $data);
     

3. Tilde Encoding:

   • Pointers with ~ (e.g., /a~1b) require URL-encoding.
   • Fix: Use Pointer\ReferenceToken::fromString() or encode manually:

     $encoded = str_replace('~', '~0', $path);
     

4. Mutability:

   • setValueOn() modifies the input array by reference. Use caution in shared contexts.

Debugging

• Inspect Tokens:

  $token->getPath(); // Returns ['a', 'b', 'c']
  $token->__toString(); // Returns '/a/b/c'
  

• Log Pointers:

  \Log::debug('Pointer path:', ['path' => $token->getPath()]);
  

Extension Points

1. Custom Validators: Extend Pointer\ReferenceToken to add domain-specific rules:

   class CustomToken extends ReferenceToken {
       public function isAllowed(array $data): bool {
           return in_array($this->getPath()[0], ['allowed', 'keys']);
       }
   }
   

2. Pointer Events: Listen for pointer operations (e.g., via events or decorators):

   $token->getValueFrom($data, function ($path) {
       \Log::info("Accessing path: " . implode('/', $path));
   });
   

3. Performance:

   • For large JSON, pre-compile pointers to avoid repeated parsing:

     $cachedToken = Pointer\ReferenceToken::fromString('/deep/nested/path');
     

Config Quirks

• No Default Config: The package is stateless; no config/json-pointer.php exists. All behavior is runtime-driven.

• Type Safety:

  • Use declare(strict_types=1) to enforce type hints (e.g., getValueFrom(array $data): mixed).