Solarium Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require dama/solarium-bundle
   

   Add to config/bundles.php (Symfony 4+):

   return [
       // ...
       DAMA\SolariumBundle\DAMASolariumBundle::class => ['all' => true],
   ];
   

2. Basic Configuration (config/packages/dama_solarium.yaml):

   dama_solarium:
       endpoints:
           default:
               scheme: http
               host: localhost
               port: 8983
               path: /solr
               core: your_core_name
   

3. First Query (in a controller/service):

   use Solarium\QueryType\Select\Query\Query;
   
   $client = $this->get('solarium.client');
   $select = $client->createSelect();
   $select->setQuery('*:*');
   $result = $client->select($select);
   

Key Starting Points

• Service Name: solarium.client (default client)
• Solarium Docs: Solarium Query API (core for queries)
• Debugging: Enable Solarium’s debug mode via config:

  dama_solarium:
      clients:
          default:
              debug: true
  

Implementation Patterns

Common Workflows

1. Query Execution

// Basic select
$select = $client->createSelect();
$select->setQuery('search_term');
$select->setFields(['id', 'title', 'score']);
$select->setStart(0)->setRows(10);
$result = $client->select($select);

// Faceted search
$facetSet = $client->createFacetSet();
$facetSet->createFacet('categories')->setField('category');
$select->addFacetSet($facetSet);

2. Document Management

// Add/update document
$update = $client->createUpdate();
$update->addDocument($document);
$update->addCommit();
$update->execute();

// Delete by ID
$update = $client->createUpdate();
$update->createDeleteQuery()->addQuery('id:123');
$update->addCommit();
$update->execute();

3. Pagination

$select = $client->createSelect();
$select->setQuery('*:*')->setStart($page * $perPage)->setRows($perPage);
$result = $client->select($select);

4. Custom Clients

# config/packages/dama_solarium.yaml
dama_solarium:
    clients:
        custom:
            endpoints: [default]
            options:
                adapter: curl
                timeout: 30

Access via service name: solarium.client.custom.

Integration Tips

Symfony Dependency Injection

Inject the client directly into services:

use Solarium\Client;

class SearchService {
    public function __construct(private Client $solarium) {}
}

Form Integration

Use Solarium for form-based searches:

// Controller
public function search(Request $request) {
    $query = $request->get('q');
    $select = $client->createSelect()->setQuery($query);
    // ...
}

Event Listeners

Trigger actions on Solarium events (e.g., post-query):

$client->getEventDispatcher()->addListener('solarium.query', function ($event) {
    // Log queries or modify them
});

Caching Responses

Cache Solarium results using Symfony’s cache system:

$cache = $this->get('cache.app');
$cacheKey = 'solr_results_' . md5($query);
if (!$cache->has($cacheKey)) {
    $result = $client->select($select);
    $cache->set($cacheKey, $result, 3600);
} else {
    $result = $cache->get($cacheKey);
}

Gotchas and Tips

Pitfalls

1. Deprecated Bundle:

   • The package is abandoned (README warning). Prefer nelmio/solarium-bundle for active maintenance.
   • If stuck with this bundle, monitor for breaking changes in Solarium 5.x.

2. Endpoint Configuration:

   • Core Misconfiguration: Forgetting to set core in endpoints will default to collection1 (Solr’s default), which may not exist.

     dama_solarium:
         endpoints:
             default:
                 core: your_core_name  # Critical!
     

3. Query Timeouts:

   • Default timeout (30s) may be too short for large datasets. Configure in clients.options:

     dama_solarium:
         clients:
             default:
                 options:
                     timeout: 60
     

4. Case Sensitivity:

   • Solr/Solarium queries are case-sensitive by default. Use lowercaseExpandedTerms="true" in select for case-insensitive searches:

     $select->setQuery('foo')->setLowercaseExpandedTerms(true);
     

5. Debugging Queries:

   • Enable debug mode to log raw Solr requests:

     dama_solarium:
         clients:
             default:
                 debug: true
     

   • Check logs for malformed queries (e.g., missing q parameter).

Debugging Tips

1. Solarium Debug Output:

   • Enable debug mode and inspect logs for raw Solr requests/responses.

2. Common Errors:

   • Connection refused: Verify Solr server is running (http://localhost:8983/solr).
   • Unknown core: Double-check core in endpoint config.
   • Invalid query: Validate syntax using Solr Query Syntax.

3. Testing Locally:

   • Use Docker for Solr:

     docker run -p 8983:8983 solr:8.11
     

   • Test queries via Solr Admin UI.

Extension Points

1. Custom Query Builders:

   • Extend Solarium’s query classes for reusable logic:

     class CustomSelect extends \Solarium\QueryType\Select\Query\Select {
         public function addHighlight($field) {
             $this->highlighting->addField($field);
             return $this;
         }
     }
     

2. Event Subscribers:

   • Hook into Solarium events for pre/post-processing:

     $client->getEventDispatcher()->addSubscriber(new class {
         public function onQuery(\Solarium\Event\QueryEvent $event) {
             $event->getQuery()->setQuery('*' . $event->getQuery()->getQuery());
         }
     });
     

3. Dynamic Endpoints:

   • Override endpoints dynamically (e.g., per environment):

     # config/packages/dama_solarium.yaml
     dama_solarium:
         endpoints:
             %env(resolve:SOLR_ENDPOINT)%: ~
     

     Set SOLR_ENDPOINT in .env:

     SOLR_ENDPOINT=http://solr-prod:8983/solr
     

4. Solr Schema Validation:

   • Validate documents against schema before indexing:

     $schema = $client->getSchema();
     if (!$schema->validate($document)) {
         throw new \RuntimeException('Document validation failed');
     }