Riak Client Pb Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies

   composer require php-riak/riak-client-pb
   

   Ensure protoc and protoc-gen-php are installed globally or via composer install as per the README.

2. Generate Protocol Buffers Run the generation script to create PHP classes from riak.proto:

   php vendor/bin/protoc-gen-php.php -o src/ -i . riak.proto -Dmultifile
   

   Place generated files in src/Generated/ (or your preferred directory).

3. First Use Case: Connecting to Riak Use the generated classes with a Riak PB client (e.g., Riak\Client\PB):

   use Riak\Client\PB\Connection;
   use Riak\Client\PB\RiakPB;
   
   $connection = new Connection('riak-node-host', 8087);
   $client = new RiakPB($connection);
   

Implementation Patterns

Core Workflows

1. CRUD Operations Use generated message classes (e.g., PutR, GetR, DelR) to interact with Riak:

   // Put a key-value pair
   $put = new \PutR();
   $put->setBucket('my-bucket');
   $put->setKey('my-key');
   $put->setValue('my-value');
   $client->send($put);
   
   // Fetch a value
   $get = new \GetR();
   $get->setBucket('my-bucket');
   $get->setKey('my-key');
   $response = $client->send($get);
   

2. Handling Responses Parse responses using generated classes (e.g., GetRResponse):

   if ($response instanceof \GetRResponse) {
       $value = $response->getValue();
   }
   

3. Error Handling Check for errors in responses (e.g., ErrorResp):

   if ($response instanceof \ErrorResp) {
       throw new \RuntimeException($response->getReason());
   }
   

Integration Tips

• Dependency Injection: Inject the RiakPB client into services for testability.
• Retry Logic: Implement retries for transient failures (e.g., network issues).
• Connection Pooling: Reuse Connection objects for performance.
• Async Operations: Use non-blocking sockets if extending for async workflows.

Gotchas and Tips

Pitfalls

1. Protocol Buffer Generation

   • Ensure protoc and protoc-gen-php are up-to-date. Mismatches may cause runtime errors.
   • Regenerate classes after updating riak.proto or dependencies.

2. Deprecated API

   • The package is abandoned (last release: 2015). Assume no compatibility with modern Riak versions (e.g., Riak TS, Riak KV 2.x+).
   • Use at your own risk; prefer basho/riak-php-client or HTTP-based clients.

3. Error Handling

   • Riak PB responses may lack detailed error messages. Log raw responses for debugging:

     error_log($response->serializeToString());
     

4. Thread Safety

   • The client is not thread-safe. Use a connection per request or synchronize access.

Debugging Tips

• Enable Verbose Logging Extend Connection to log raw PB messages:

  $connection->setLogger(function ($message) {
      error_log($message);
  });
  

• Validate Protobuf Schema Use protoc --decode_raw to inspect binary responses:

  protoc --decode_raw='.GetRResponse' < response.bin
  

Extension Points

1. Custom Middleware Wrap RiakPB to add logic (e.g., auth, metrics):

   class AuthRiakPB extends RiakPB {
       public function send($request) {
           $request->setAuthToken('your-token');
           return parent::send($request);
       }
   }
   

2. Batch Operations Extend for multi-request batching (e.g., MultiPutR):

   $batch = new \MultiPutR();
   $batch->addPut($put1);
   $batch->addPut($put2);
   $client->send($batch);
   

3. Alternative Transports Replace Connection with a custom socket implementation (e.g., for gRPC).