Elastica Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Run:

   composer require friendsofsymfony/elastica-bundle
   

   Enable the bundle in AppKernel.php:

   new FOS\ElasticaBundle\FOSElasticaBundle(),
   

2. Basic Configuration Define a client in config/packages/fos_elastica.yaml (Symfony 4+) or config.yml (Symfony 2/3):

   fos_elastica:
       clients:
           default: { host: localhost, port: 9200 }
   

3. First Use Case Create a simple indexer for a Doctrine entity (e.g., Product):

   # config/packages/fos_elastica.yaml
   fos_elastica:
       indexes:
           product:
               types:
                   product:
                       properties:
                           name: ~
                           price: ~
                       persistence:
                           driver: orm
                           model: App\Entity\Product
                           provider: ~
                           finder: ~
   

   Run the indexer:

   php bin/console fos:elastica:populate
   

Implementation Patterns

Core Workflows

1. Indexing Entities

   • Use persistence.driver: orm for Doctrine entities.
   • Customize mappings via properties (e.g., nested objects, dynamic fields).
   • Example for nested objects:

     properties:
         reviews:
             type: nested
             properties:
                 rating: ~
                 comment: ~
     

2. Querying Elasticsearch

   • Use the Elastica client in services/controllers:

     use FOS\ElasticaBundle\Finder\PaginatedFinderInterface;
     
     class ProductSearchController
     {
         public function search(PaginatedFinderInterface $finder)
         {
             $results = $finder->find('product', [
                 'query' => [
                     'match' => ['name' => 'laptop']
                 ]
             ]);
             return $this->render('search.html.twig', ['results' => $results]);
         }
     }
     

3. Partial Indexing

   • Use fos:elastica:populate with --partial to update only changed entities:

     php bin/console fos:elastica:populate --partial
     

4. Custom Indexers

   • Extend FOS\ElasticaBundle\Indexer\AbstractIndexer for custom logic (e.g., pre-processing data before indexing).

Integration Tips

• Symfony Forms: Use FOS\ElasticaBundle\Form\Type\ElasticaType for search-as-you-type fields.
• Event Listeners: Hook into fos_elastica.index.populate or fos_elastica.index.delete events for side effects (e.g., logging).
• Cron Jobs: Schedule fos:elastica:populate via Symfony’s CronBundle or system cron.

Gotchas and Tips

Pitfalls

1. Version Mismatches

   • Ensure friendsofsymfony/elastica-bundle and ruflin/elastica versions align with your Symfony/Elasticsearch versions.
   • Check compatibility matrix for conflicts.

2. Index Naming Collisions

   • Default index names are derived from the YAML key (e.g., product). Override with index_name:

     indexes:
         product_index: { ... }
     

3. Case Sensitivity in Mappings

   • Elasticsearch mappings are case-sensitive. Use keyword for exact matches:

     properties:
         sku: { type: keyword }
     

4. Partial Indexing Quirks

   • --partial skips entities not found in the database. Ensure your finder is correctly configured to avoid missing data.

Debugging

• Enable Debugging:

  fos_elastica:
      clients:
          default:
              host: localhost
              port: 9200
              debug: true  # Logs raw Elasticsearch requests/responses
  

• Check Index Status:

  php bin/console fos:elastica:status
  

• Clear Cache:

  php bin/console cache:clear
  php bin/console fos:elastica:clear
  

Extension Points

1. Custom Providers

   • Implement FOS\ElasticaBundle\Provider\AbstractProvider for non-Doctrine data sources (e.g., API data).

2. Dynamic Mappings

   • Use fos_elastica.index.create event to modify mappings dynamically:

     // src/EventListener/ElasticaListener.php
     public function onIndexCreate(IndexEvent $event)
     {
         $event->getIndex()->getMapping()->addType('product', [
             'properties' => [
                 'dynamic_date' => ['type' => 'date']
             ]
         ]);
     }
     

3. Aliases

   • Manage index aliases via fos_elastica.index.alias event for zero-downtime reindexing.

4. Bulk Processing

   • Override FOS\ElasticaBundle\Indexer\AbstractIndexer::indexDocument() for custom bulk logic (e.g., batch inserts).