Seal Solr Adapter Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies:

   composer require cmsig/seal cmsig/seal-solr-adapter solarium/solarium
   

   • solarium/solarium is required for Solr client functionality.

2. Configure Solr Client: Define a Solr client instance using Solarium’s Client class with a Curl adapter:

   use Solr\Client;
   use Solarium\Core\Client\Adapter\Curl;
   use Symfony\Component\EventDispatcher\EventDispatcher;
   
   $client = new Client(new Curl(), new EventDispatcher(), [
       'endpoint' => [
           'localhost' => [
               'scheme' => 'http',
               'host' => '127.0.0.1',
               'port' => '8983',
               'username' => 'solr',
               'password' => 'SolrRocks',
           ],
       ],
   ]);
   

3. Initialize SEAL Engine: Pass the Solr client to the SolrAdapter and integrate with SEAL’s schema:

   use CmsIg\Seal\Adapter\Solr\SolrAdapter;
   use CmsIg\Seal\Engine;
   
   $engine = new Engine(new SolrAdapter($client), $schema);
   

4. First Use Case: Index a document:

   $document = $engine->index('collection_name', [
       'id' => '123',
       'title' => 'Test Document',
       'content' => 'Searchable content...',
   ]);
   

Where to Look First

• README.md: Focus on the "Usage" section for basic setup.
• Solarium Docs: Refer to Solarium’s documentation for Solr client intricacies (e.g., authentication, TLS).
• SEAL Docs: Check cmsig/seal for schema definitions and query patterns.

Implementation Patterns

Core Workflows

1. Indexing Documents: Use SEAL’s index() method to push documents to Solr collections:

   $engine->index('products', [
       'sku' => 'ABC123',
       'name' => 'Laptop',
       'price' => 999.99,
   ]);
   

   • Collections: SEAL maps Solr collections to logical indexes (e.g., products, articles).

2. Querying: Leverage SEAL’s query builder for Solr-compatible syntax:

   $results = $engine->search('products', [
       'query' => 'laptop',
       'filter' => ['price' => ['range' => ['from' => 500]]],
   ]);
   

3. Bulk Operations: Use Solr’s batch API via SEAL’s bulk methods:

   $engine->bulkIndex('products', [
       ['id' => '1', 'name' => 'Item 1'],
       ['id' => '2', 'name' => 'Item 2'],
   ]);
   

Integration Tips

1. Configuration Management:

   • Store Solr credentials in .env and use DSN strings for flexibility:

     SEAL_SOLR_DSN="solr://solr:SolrRocks@127.0.0.1:8983?tls=true"
     

   • Parse DSN in a service provider:

     $dsn = parse_url($_ENV['SEAL_SOLR_DSN']);
     $client = new Client(new Curl(), new EventDispatcher(), [
         'endpoint' => [$dsn['host'] => [
             'scheme' => $dsn['scheme'] ?? 'http',
             'host' => parse_url($dsn['host'], PHP_URL_HOST),
             'port' => $dsn['port'] ?? 8983,
             'username' => $dsn['user'] ?? null,
             'password' => $dsn['pass'] ?? null,
         ]],
     ]);
     

2. Schema Alignment:

   • Ensure SEAL’s schema matches Solr’s dynamic fields or explicit schema.xml:

     $schema = new \CmsIg\Seal\Schema\Schema([
         'fields' => [
             'id' => ['type' => 'string', 'required' => true],
             'name' => ['type' => 'text'],
             'price' => ['type' => 'float'],
         ],
     ]);
     

3. Event Handling:

   • Subscribe to SEAL events (e.g., DocumentIndexed) to trigger post-indexing logic:

     $dispatcher->addListener('document.indexed', function ($event) {
         Log::info('Indexed document: ' . $event->getDocument()->getId());
     });
     

4. Error Handling:

   • Wrap Solr operations in try-catch blocks to handle timeouts or connection issues:

     try {
         $engine->index('collection', $document);
     } catch (\Solarium\Exception\SolrConnectionException $e) {
         report($e);
         // Fallback to cache or retry logic
     }
     

Gotchas and Tips

Pitfalls

1. Authentication:

   • Solr’s configsets API requires authentication by default. Either:
     • Configure Solr with solr.disableConfigSetsCreateAuthChecks=true in solrconfig.xml.
     • Ensure credentials are provided in the client config (as shown in the README).

2. Cloud Mode Requirements:

   • The adapter assumes Solr is running in cloud mode (SolrCloud). Single-node setups may fail if collections aren’t properly configured.

3. Schema Mismatches:

   • SEAL’s schema must align with Solr’s dynamic fields or explicit schema. Dynamic fields (e.g., *_text) may cause unexpected behavior if not defined in Solr.

4. Connection Timeouts:

   • Solr operations can hang. Set timeouts in the Solarium client:

     $client = new Client(new Curl(), new EventDispatcher(), [
         'timeout' => 5.0, // 5 seconds
     ]);
     

Debugging

1. Enable Solarium Logging: Add a logger to the Solarium client to inspect raw Solr requests/responses:

   use Psr\Log\LoggerInterface;
   use Solarium\Core\Client\Adapter\Curl;
   
   $adapter = new Curl();
   $adapter->setLogger(new \Monolog\Logger('solr'));
   $client = new Client($adapter, new EventDispatcher(), [...]);
   

2. Check Solr Logs:

   • Solr logs (typically in $SOLR_HOME/logs) are invaluable for diagnosing issues like schema errors or query failures.

3. Validate Collections:

   • Ensure collections exist before indexing:

     if (!$engine->collectionExists('products')) {
         $engine->createCollection('products');
     }
     

Tips

1. Use DSN for Environment Flexibility:

   • DSN strings (e.g., solr://user:pass@host:port?tls=true) simplify switching between dev/staging/prod environments.

2. Leverage Solr’s Atomic Updates:

   • For partial updates, use Solr’s atomic update syntax via SEAL’s update() method:

     $engine->update('products', '123', [
         'price' => ['set' => 899.99],
     ]);
     

3. Batch Indexing for Performance:

   • Batch operations reduce network overhead:

     $engine->bulkIndex('products', array_map(fn ($item) => [
         'id' => $item['id'],
         'name' => $item['name'],
     ], $items));
     

4. Monitor Collection Health:

   • Use Solr’s API to check collection status:

     $status = $engine->getCollectionStatus('products');
     

5. Extend the Adapter:

   • Override SolrAdapter to add custom logic (e.g., pre-processing documents):

     class CustomSolrAdapter extends SolrAdapter {
         public function index($collection, array $document) {
             $document['processed_at'] = now()->toDateTimeString();
             return parent::index($collection, $document);
         }
     }