Vdm Library Elastic Transport Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require 3slab/vdm-library-elastic-transport-bundle
   

   Ensure your config/bundles.php includes:

   return [
       // ...
       Vdm\Library\ElasticTransportBundle\VdmLibraryElasticTransportBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console vdm:elastic:transport:config
   

   Update config/packages/vdm_library_elastic_transport.yaml with your Elasticsearch endpoint and credentials.

3. First Use Case Inject the transport client in a service:

   use Vdm\Library\ElasticTransportBundle\Client\ElasticTransportClient;
   
   class MyService
   {
       public function __construct(private ElasticTransportClient $elasticClient) {}
   
       public function searchDocuments(): array
       {
           return $this->elasticClient->search(['index' => 'documents', 'body' => ['query' => ['match_all' => new \stdClass()]]]);
       }
   }
   

Implementation Patterns

Core Workflows

1. Index Management Use the client to create/update indices dynamically:

   $this->elasticClient->indices()->create(['index' => 'products', 'body' => ['settings' => ['number_of_shards' => 3]]]);
   

2. CRUD Operations Leverage the transport client for raw Elasticsearch operations:

   // Index a document
   $this->elasticClient->index(['index' => 'users', 'id' => 1, 'body' => ['name' => 'John']]);
   
   // Retrieve a document
   $result = $this->elasticClient->get(['index' => 'users', 'id' => 1]);
   
   // Update a document
   $this->elasticClient->update(['index' => 'users', 'id' => 1, 'body' => ['doc' => ['name' => 'John Doe']]]);
   
   // Delete a document
   $this->elasticClient->delete(['index' => 'users', 'id' => 1]);
   

3. Search Queries Build complex queries using the client:

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

4. Bulk Operations Use bulk API for efficiency:

   $bulkBody = [
       ['index' => ['_index' => 'users', '_id' => 1]],
       ['name' => 'Alice'],
       ['index' => ['_index' => 'users', '_id' => 2]],
       ['name' => 'Bob'],
   ];
   $this->elasticClient->bulk(['body' => $bulkBody]);
   

Integration Tips

• Symfony Dependency Injection: Bind the ElasticTransportClient to a custom interface for easier testing/mocking.
• Event Listeners: Attach listeners to Elasticsearch events (e.g., index creation) via Symfony’s event dispatcher.
• Doctrine ORM: Use the bundle alongside Doctrine for hybrid data storage (e.g., metadata in SQL, full-text in Elasticsearch).

Gotchas and Tips

Common Pitfalls

1. Deprecated Elasticsearch PHP Client The bundle wraps the older elasticsearch/elasticsearch PHP client (v6.x). If you need newer features (e.g., v7/v8), consider:

   • Upgrading to elastic/elasticsearch directly.
   • Forking the bundle to use the newer client.

2. Configuration Overrides The bundle’s default config assumes a local Elasticsearch instance. For cloud providers (e.g., AWS OpenSearch), override:

   vdm_library_elastic_transport:
       hosts: ['https://search-abc123.us-east-1.es.amazonaws.com:443']
       auth:
           username: 'admin'
           password: 'password'
   

3. Error Handling The bundle does not include built-in retry logic for transient failures. Wrap calls in a try-catch:

   try {
       $this->elasticClient->search($query);
   } catch (\Elasticsearch\Common\Exceptions\ElasticsearchException $e) {
       // Log and retry or fallback
   }
   

4. Index Aliases The bundle does not natively support index aliases. For zero-downtime deployments, manage aliases manually or extend the client:

   $this->elasticClient->indices()->putAlias(['index' => 'products_v1', 'name' => 'products']);
   

Debugging Tips

• Enable Logging: Add to config/packages/monolog.yaml:

  handlers:
      elastic:
          type: stream
          path: "%kernel.logs_dir%/elastic.log"
          level: debug
          channels: ["!event"]
  

  Then enable debug mode for the Elasticsearch client in config:

  vdm_library_elastic_transport:
      debug: true
  

• Raw Responses: Inspect raw responses for debugging:

  $response = $this->elasticClient->search($query);
  \Log::debug('Elasticsearch Response', ['response' => $response->getBody()]);
  

Extension Points

1. Custom Clients Extend the base client to add domain-specific methods:

   class CustomElasticClient extends ElasticTransportClient
   {
       public function searchUsers(array $criteria): array
       {
           return $this->search([
               'index' => 'users',
               'body' => [
                   'query' => [
                       'bool' => [
                           'filter' => $this->buildFilters($criteria),
                       ],
                   ],
               ],
           ]);
       }
   }
   

2. Middleware Add request/response middleware for logging, auth, or transformation:

   $client = new ElasticTransportClient($hosts, $config);
   $client->getTransport()->addMiddleware(new MyMiddleware());
   

3. Console Commands Create custom commands for Elasticsearch admin tasks:

   namespace App\Command;
   
   use Symfony\Component\Console\Command\Command;
   use Vdm\Library\ElasticTransportBundle\Client\ElasticTransportClient;
   
   class OptimizeIndicesCommand extends Command
   {
       protected static $defaultName = 'vdm:elastic:optimize';
   
       public function __construct(private ElasticTransportClient $client)
       {
           parent::__construct();
       }
   
       protected function execute(InputInterface $input, OutputInterface $output): int
       {
           $this->client->indices()->optimize(['index' => 'products']);
           return Command::SUCCESS;
       }
   }