Elastica Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require friendsofsymfony/elastica-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       FriendsOfSymfony\ElasticaBundle\FriendsOfSymfonyElasticaBundle::class => ['all' => true],
   ];
   

2. Configure Elasticsearch Edit config/packages/fos_elastica.yaml:

   fos_elastica:
       clients:
           default: { host: localhost, port: 9200 }
       indexes:
           app:
               types:
                   product:
                       properties:
                           name: ~
                           price: ~
                       persistence:
                           driver: orm
                           model: App\Entity\Product
                           provider: ~
                           listener: ~
   

3. First Use Case Create an entity (e.g., Product) and annotate it with @Elastica\Document:

   use Elastica\Annotation as Elastica;
   
   /**
    * @Elastica\Document(repositoryClass="App\Repository\ProductElasticaRepository")
    */
   class Product {}
   

   Run:

   php bin/console fos:elastica:populate
   

Implementation Patterns

Common Workflows

1. Indexing Entities Use Doctrine listeners for automatic indexing:

   # config/packages/fos_elastica.yaml
   fos_elastica:
       indexes:
           app:
               types:
                   product:
                       persistence:
                           listener: true  # Auto-index on CRUD
   

2. Custom Mappings Override default mappings via YAML or PHP:

   properties:
       name:
           type: text
           analyzer: custom_analyzer
   

3. Searching Inject the repository and query:

   use FriendsOfSymfony\ElasticaBundle\Finder\PaginatedFinderInterface;
   
   class ProductSearchService {
       public function __construct(private PaginatedFinderInterface $finder) {}
   
       public function search(string $query): array {
           return $this->finder->find('app', Product::class, ['query_string' => ['query' => $query]]);
       }
   }
   

4. Bulk Operations Use the fos:elastica:populate command with --batch-size for large datasets:

   php bin/console fos:elastica:populate --batch-size=100
   

Integration Tips

• Symfony Serializer: Leverage @Serializer\SerializedName for field mapping.
• Events: Subscribe to ElasticaIndexEvent for pre/post-indexing logic.
• Custom Providers: Implement Elastica\Provider\ProviderInterface for non-Doctrine data.

Gotchas and Tips

Pitfalls

1. Mapping Conflicts

   • Elasticsearch mappings are immutable. Avoid changing type after initial index creation.
   • Fix: Delete and recreate the index if needed:

     php bin/console fos:elastica:remove-index
     php bin/console fos:elastica:create-index
     

2. Listener Overhead

   • Auto-indexing listeners (listener: true) trigger on every Doctrine event (save/remove/flush).
   • Tip: Disable for high-traffic entities or use @Elastica\Index annotations selectively.

3. Propel Limitation

   • Propel support is experimental. Use Doctrine for full features.

4. Pagination Quirks

   • PaginatedFinder uses Elasticsearch’s from/size. For large datasets, prefer search_after:

     $finder->find('app', Product::class, ['query' => $query, 'sort' => ['price']]);
     

Debugging

• Check Index Status:

  php bin/console fos:elastica:status
  

• Log Queries: Enable debug mode in fos_elastica.yaml:

  client: { debug: true }
  

• Common Errors:
  • NoHandlerFoundException: Verify model and repositoryClass in YAML match your entity.
  • ConnectionRefused: Confirm Elasticsearch is running (http://localhost:9200).

Extension Points

1. Custom Indexers Extend Elastica\Indexer\IndexerInterface for custom logic:

   class CustomIndexer implements IndexerInterface {
       public function indexDocument(DocumentInterface $document, $data) { ... }
   }
   

   Register in services.yaml:

   services:
       App\Indexer\CustomIndexer:
           tags: [fos_elastica.indexer]
   

2. Dynamic Mappings Use fos_elastica.dynamic_mapping event to modify mappings at runtime:

   $event->setMapping(['dynamic' => 'strict']);
   

3. Async Indexing Offload indexing with Symfony Messenger:

   use FriendsOfSymfony\ElasticaBundle\Indexer\IndexerInterface;
   
   class IndexMessage implements MessageInterface {
       public function __construct(private IndexerInterface $indexer, private $entity) {}
       public function __invoke() { $this->indexer->index($this->entity); }
   }