Solr Laravel Package

Getting Started

Minimal Setup

1. Install Ibexa DXP (prerequisite):

   composer create-project ibexa/dxp-project my-project
   cd my-project
   

2. Configure Solr:

   • Install and run a local Solr instance (e.g., via Docker or standalone).
   • Configure config/packages/ibexa_solr.yaml:

     ibexa_solr:
         client:
             endpoint: 'http://localhost:8983/solr'
             cores: ['ibexa']
             auth:
                 username: 'solr'
                 password: 'SolrRocks'
     

3. First Search Query:

   use Ibexa\Contracts\Core\Repository\SearchService;
   use Ibexa\Contracts\Core\Repository\Values\Content\Query;
   
   $searchService = $repository->getSearchService();
   $query = new Query();
   $query->query = new \Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion\FullText('*');
   $searchResult = $searchService->findContent($query);
   

4. Verify Indexing:

   • Use Ibexa’s admin interface or CLI to index content:

     php bin/console ibexa:content:reindex
     

Key Entry Points

• SearchService: Core interface for queries ($repository->getSearchService()).
• Query Builder: Chain criteria, sorts, and aggregations.
• ContentHandler: Customize field mappings via Ibexa\Solr\FieldType\FieldTypeHandler.

Implementation Patterns

1. Query Construction

Workflow:

• Use criterion visitors to translate Ibexa criteria into Solr queries:

  $query = new Query();
  $query->query = new \Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion\LogicalAnd([
      new \Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion\ContentTypeIdentifier('article'),
      new \Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion\DateRange('published', '2023-01-01', '2023-12-31'),
  ]);
  

• Sorting:

  $query->sortClauses = [
      new \Ibexa\Contracts\Core\Repository\Values\Content\Query\SortClause\Field('content_name', 'asc'),
  ];
  

• Aggregations (e.g., facet counts):

  $query->aggregations = [
      new \Ibexa\Contracts\Core\Repository\Values\Content\Query\Aggregation\Term('content_type_identifier'),
  ];
  

Tip: Use SearchService::findContent() for results or SearchService::findContentCount() for counts.

2. Custom Field Mappings

Pattern: Extend FieldTypeHandler for non-standard fields (e.g., custom field types).

use Ibexa\Solr\FieldType\FieldTypeHandler;

class CustomFieldHandler extends FieldTypeHandler
{
    public function getFieldType(): string
    {
        return 'custom_field_type';
    }

    public function getFieldName(): string
    {
        return 'custom_field';
    }

    public function getFieldValue($content, $field, $languageCode = null)
    {
        return $content->getFieldValue($field->value)->value;
    }
}

Register in services.yaml:

services:
    Ibexa\Solr\FieldType\FieldTypeHandler\CustomFieldHandler:
        tags: ['ibexa.solr.field_type_handler']

3. Embedding Search (Vector Search)

Use Case: Semantic search with dense vectors (e.g., AI-generated embeddings).

$query = new Query();
$query->query = new \Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion\Embedding(
    'vector_field',
    [0.1, 0.2, 0.3], // Your embedding vector
    0.7 // Similarity threshold
);

Prerequisite: Configure Solr’s knn plugin and map the field in schema.xml.

4. Bulk Indexing

Pattern: Use ContentService + SearchService for efficient reindexing:

$contentService = $repository->getContentService();
$searchService = $repository->getSearchService();

$contentInfoList = $contentService->loadContentInfoList([
    new \Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion\ContentId(1),
    new \Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion\ContentId(2),
]);

$searchService->deleteContent($contentInfoList);
$searchService->indexContent($contentInfoList);

Optimization: Batch operations with ContentService::loadContentInfoList() and SearchService::indexContent().

5. Solr Schema Customization

Workflow:

1. Extend Schema: Copy Solr’s managed-schema to your project and add fields. Example for a vector_field:

   <field name="vector_field" type="knn_vector" indexed="true" stored="true"/>
   <fieldType name="knn_vector" class="solr.KnnVectorField" dimension="3"/>
   

2. Reconfigure Ibexa:

   ibexa_solr:
       schema:
           custom_fields:
               vector_field: ~
   

Gotchas and Tips

Pitfalls

1. Field Name Collisions:

   • Ibexa maps fields to Solr using fieldName (e.g., content_name). Override in FieldTypeHandler if conflicts arise.
   • Fix: Use getFieldName() to customize mappings.

2. Solr Core Mismatch:

   • Ensure the Solr core name in ibexa_solr.yaml matches the core defined in Solr (ibexa by default).
   • Debug: Check Solr admin UI (http://localhost:8983/solr/#/ibexa) for core status.

3. Deprecated APIs:

   • Avoid Facet classes (deprecated in v5). Use Aggregation instead:

     // Old (deprecated)
     $query->facet = new \Ibexa\Contracts\Core\Repository\Values\Content\Query\Facet\Term('content_type');
     
     // New
     $query->aggregations = [new \Ibexa\Contracts\Core\Repository\Values\Content\Query\Aggregation\Term('content_type')];
     

4. Timeouts:

   • Default HTTP client timeout is 30s. Adjust in ibexa_solr.yaml:

     ibexa_solr:
         client:
             timeout: 60 # seconds
             max_retries: 3
     

5. Embedding Fields:

   • Requires Solr’s knn plugin (v9.8+). Enable in solrconfig.xml:

     <searchComponent name="knn" class="solr.KnnComponent"/>
     

   • Error: Field 'vector_field' not found → Verify schema.xml and core reload.

Debugging Tips

1. Query Logging: Enable Solr logging to inspect raw queries:

   ibexa_solr:
       debug: true
   

   • Logs appear in var/log/ibexa_solr.log.

2. Solr Admin UI:

   • Use http://localhost:8983/solr/#/~collections/ibexa to inspect documents, schema, and query performance.

3. Common Errors:

   • "No cores found": Verify ibexa_solr.yaml and Solr core creation.

     curl -X POST -H 'Content-type:application/json' --data-binary '{
       "create": "ibexa",
       "instanceDir": "solr",
       "configSet": "ibexa",
       "numShards": "1",
       "replicationFactor": "1"
     }' http://localhost:8983/api/collections
     

   • "Field not indexed": Check schema.xml and FieldTypeHandler mappings.

Extension Points

1. Custom Criterion Visitors: Extend \Ibexa\Solr\Visitor\CriterionVisitor to support new criteria:

   class CustomCriterionVisitor extends CriterionVisitor
   {
       public function visitCustomCriterion(CustomCriterion $criterion)
       {
           return new \SolrQuery('custom_field:' . $criterion->value);
       }
   }
   

   Register:

   services:
       App\Solr\Visitor\CustomCriterionVisitor:
           tags: ['ibexa.solr.criterion_visitor']
   

2