Jsonpath Laravel Package

Getting Started

Start by requiring the package via Composer:

composer require softcreatr/jsonpath

Then, instantiate the JSONPath parser with your JSON (or decoded array). The simplest use case is extracting nested data:

use Softcreatr\JsonPath\JsonPath;

$json = '{"users": [{"name": "Alice", "role": "admin"}, {"name": "Bob", "role": "user"}]}';
$jp = new JsonPath();
$results = $jp->find($json, '$.users[*].name'); // Returns ['Alice', 'Bob']

Check the README for syntax basics and start with basic dot notation ($.key) and wildcard ($[*]) selectors.

Implementation Patterns

• API Response Parsing: Use JSONPath to extract specific fields from third-party API responses (e.g., Stripe webhooks, GitHub API payloads) without deep array_merge or nested loops.
• Configuration Validation: Traverse dynamic config structures (e.g., multi-tenant JSON configs) to validate presence/value of required keys before bootstrapping services.
• Data Transformation: Combine with Laravel’s collect() to map filtered results:

  $paths = $jp->find($json, '$.items[?(@.status == "active")]');
  $ids = collect($paths)->pluck('id')->all();
  

• Testing Helpers: In feature tests, verify expected data exists in JSON responses using assertions like assertJsonPath($json, '$.data.id', 123).
• Laravel Service Binding: Bind JsonPath as a singleton in a service provider for reuse across your app, especially in job handlers processing external payloads.

Gotchas and Tips

• No Built-in Laravel Integration: This is a standalone library — you’ll need to manually decode JSON to arrays before passing if your input is a string (most methods expect array or stdClass).
• Filter Syntax Quirk: Filter expressions require valid JSONPath syntax inside brackets (e.g., $[?(@.score > 10)]), not PHP-like syntax. Comparison operators are strict (==, !=, >, <, etc.), and strings need quotes.
• Path Return vs Value Return: Use findAll() to get both values and paths (e.g., ['$.users[0].name']), useful for debugging or deep structural mapping.
• Empty Results Are Arrays: $jp->find($json, '$.missing') returns an empty array—not null. Guard against this in conditions with empty($results).
• Extension Tip: Extend \Softcreatr\JsonPath\JsonPath to add domain-specific helpers (e.g., findActiveUsers()) that pre-apply common filters.
• Performance: For large payloads (>1MB), avoid repeated parses—cache decoded data and reuse JsonPath instances (it’s stateless, so safe for reuse).