Guzzle Jsonrpc Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require graze/guzzle-jsonrpc:~3.0
   

   Ensure your project uses GuzzleHTTP 6 (or compatible versions as per the package's branches).

2. Basic Client Initialization:

   use Graze\GuzzleHttp\JsonRpc\Client;
   
   $client = Client::factory('http://your-jsonrpc-endpoint');
   

3. First Use Case: Send a simple request:

   $response = $client->send(
       $client->request(null, 'methodName', ['param1', 'param2'])
   );
   

Implementation Patterns

Core Workflows

1. Synchronous Requests:

   // Single request
   $response = $client->send(
       $client->request(1, 'getUser', ['userId' => 123])
   );
   
   // Batch requests
   $responses = $client->sendAll([
       $client->request(1, 'method1', []),
       $client->request(2, 'method2', []),
   ]);
   

2. Asynchronous Requests (using Guzzle Promises):

   $promise = $client->sendAsync(
       $client->request(1, 'asyncMethod', [])
   );
   $promise->then(function ($response) {
       // Handle response
   });
   

3. Notifications (fire-and-forget):

   $client->send(
       $client->notification('logEvent', ['event' => 'user_login'])
   );
   

Integration Tips

• Middleware/Subscribers: Register Guzzle middleware (e.g., for logging or error handling):

  $client = new Client(
      'http://endpoint',
      ['subscribers' => [new \GuzzleHttp\Subscriber\RetrySubscriber()]]
  );
  

• Error Handling: Enable RPC error exceptions:

  $client = Client::factory('http://endpoint', ['rpc_error' => true]);
  try {
      $client->send($client->request(1, 'method', []));
  } catch (\Graze\GuzzleHttp\JsonRpc\Exception\RequestException $e) {
      // Handle RPC errors
  }
  

• Custom Headers/Config: Pass Guzzle options via the client constructor:

  $client = Client::factory('http://endpoint', [
      'headers' => ['Authorization' => 'Bearer token'],
      'timeout'  => 10,
  ]);
  

Gotchas and Tips

Pitfalls

1. Deprecation Warning: The package is abandoned (last release: 2018). Use at your own risk or fork it.

   • Mitigation: Monitor for breaking changes in newer Guzzle versions (e.g., Guzzle 7+).

2. PHP 7+ JSON Parsing: Empty string responses may cause issues (fixed in 3.2.1). Ensure your server returns valid JSON.

3. Async Quirks:

   • Promises may not propagate exceptions consistently. Use .catch() for robust error handling:

     $promise->catch(function ($exception) {
         log::error($exception->getMessage());
     });
     

4. Batch Requests:

   • Order of responses in sendAll() matches the input array. Validate responses by ID:

     foreach ($responses as $response) {
         if ($response->getId() === 1) { /* Handle */ }
     }
     

Debugging Tips

• Enable Guzzle Debugging:

  $client = Client::factory('http://endpoint', [
      'debug' => true,
  ]);
  

  Check $client->getHandlerStack() for middleware.

• Inspect Raw Responses:

  $response = $client->send($request);
  $rawBody = $response->getBody()->getContents();
  

Extension Points

1. Custom Response Handling: Extend the Client class to modify response processing:

   class CustomClient extends Client {
       protected function processResponse($response) {
           // Custom logic
           return parent::processResponse($response);
       }
   }
   

2. Middleware for JSON-RPC: Add pre/post-processing middleware:

   $stack = \GuzzleHttp\HandlerStack::create();
   $stack->push(\GuzzleHttp\Middleware::tap(function ($request) {
       // Modify request
   }));
   $client = new Client('http://endpoint', ['handler' => $stack]);
   

3. Batch Optimization: For high-volume batches, consider:

   • Using sendAllAsync() with then() for parallel processing.
   • Implementing exponential backoff for retries.