Phprom Client Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require chaseisabelle/phprom-client
   

   Ensure your project uses PHP 7.4+ (last release compatibility).

2. First Use Case: Query Execution

   use ChaseIsabelle\PhpromClient\Client;
   
   $client = new Client('http://localhost:9200'); // Default Phprom endpoint
   $response = $client->search('index_name', ['match_all' => new \stdClass()]);
   

3. Key Files to Explore

   • src/Client.php – Core HTTP client logic.
   • src/RequestBuilder.php – Query construction helpers.
   • src/Exceptions/ – Error handling patterns.

Implementation Patterns

Workflow: CRUD Operations

1. Indexing Documents

   $client->index('users', 1, ['name' => 'John']);
   

2. Searching with DSL

   $query = [
       'query' => [
           'bool' => [
               'must' => [
                   ['match' => ['name' => 'John']],
                   ['range' => ['age' => ['gte' => 30]]]
               ]
           ]
       ]
   ];
   $results = $client->search('users', $query);
   

3. Bulk Operations

   $bulkData = [
       ['index' => ['_index' => 'users', '_id' => 1]],
       ['name' => 'Alice'],
       ['index' => ['_index' => 'users', '_id' => 2]],
       ['name' => 'Bob']
   ];
   $client->bulk($bulkData);
   

Integration Tips

• Laravel Service Provider Bind the client in AppServiceProvider for dependency injection:

  $this->app->singleton(Client::class, fn() => new Client(config('phprom.url')));
  

• Query Builder Abstraction Extend RequestBuilder to add domain-specific methods:

  class UserQueryBuilder extends RequestBuilder {
      public function activeUsers() {
          return $this->addQuery([
              'bool' => ['must_not' => ['term' => ['active' => false]]]
          ]);
      }
  }
  

• Async Requests Use Guzzle’s async capabilities (if underlying HTTP client supports it):

  $promise = $client->getHttpClient()->requestAsync('GET', '/users/_search');
  

Gotchas and Tips

Pitfalls

1. Deprecated Endpoints The package predates Phprom’s API changes (e.g., _msearch vs. /_search). Verify endpoints against Phprom’s docs.

2. Error Handling Exceptions are thrown for HTTP errors (4xx/5xx), but responses may still contain useful data. Check $response->getBody() for details:

   try {
       $client->search('nonexistent', []);
   } catch (\ChaseIsabelle\PhpromClient\Exception\ClientException $e) {
       $error = json_decode($e->getResponse()->getBody(), true);
   }
   

3. Serialization Quirks The library uses json_encode/json_decode by default. For custom objects, implement JsonSerializable or configure a custom encoder:

   $client->setEncoder(new CustomJsonEncoder());
   

Debugging Tips

• Enable Debug Mode

  $client->setDebug(true); // Logs raw requests/responses
  

• Mocking for Tests Use a test HTTP client (e.g., Guzzle’s MockHandler):

  $mock = new MockHandler([new Response(200, [], '{"hits": []}')]);
  $client->setHttpClient(new Client($mock));
  

Extension Points

1. Custom HTTP Client Replace the default client (Guzzle) by implementing ChaseIsabelle\PhpromClient\Contracts\HttpClient:

   $client->setHttpClient(new CustomHttpClient());
   

2. Middleware Add request/response middleware via the setMiddleware method:

   $client->setMiddleware(function ($request) {
       $request->setHeader('X-Custom-Header', 'value');
   });
   

3. Response Transformation Override transformResponse in a custom client class to parse responses differently:

   class CustomClient extends Client {
       protected function transformResponse($response) {
           return parent::transformResponse($response)->withMetadata(['custom' => true]);
       }
   }