Solarium Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require nelmio/solarium-bundle
   

   Add the bundle to config/bundles.php (Laravel 5.4+):

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

2. Basic Configuration (in config/services.php or config/nelmio_solarium.php):

   'nelmio_solarium' => [
       'endpoints' => [
           'default' => [
               'scheme' => 'http',
               'host' => 'localhost',
               'port' => 8983,
               'path' => '/solr',
               'core' => 'your_core_name',
           ],
       ],
   ],
   

3. First Use Case: Inject the Solarium client via Laravel's service container:

   use Solarium\Client;
   
   class YourService {
       protected $solarium;
   
       public function __construct(Client $solarium) {
           $this->solarium = $solarium;
       }
   
       public function search($query) {
           $query = $this->solarium->createSelect();
           $query->setQuery($query);
           $result = $this->solarium->select($query);
           return $result->getResults();
       }
   }
   

Implementation Patterns

Core Workflows

1. Querying Solr:

   // Basic select query
   $query = $this->solarium->createSelect();
   $query->setQuery('laravel');
   $query->setFields(['id', 'title', 'description']);
   $result = $this->solarium->select($query);
   
   // Pagination
   $query->setStart(0)->setRows(10);
   
   // Filtering
   $filter = $this->solarium->createFilterQuery();
   $filter->createLocalParam('fq', ['status:active']);
   $query->addFilterQuery($filter);
   

2. Indexing Documents:

   $update = $this->solarium->createUpdate();
   $update->addDocument([
       'id' => '123',
       'title' => 'Laravel Solr',
       'description' => 'Search with Solr',
   ]);
   $this->solarium->update($update);
   $this->solarium->commit();
   

3. Dependency Injection: Bind custom clients in AppServiceProvider:

   public function register() {
       $this->app->bind('solarium.client.custom', function ($app) {
           $config = $app['config']['nelmio_solarium.clients.custom'];
           return new \Solarium\Client($config['endpoints']);
       });
   }
   

4. Event Listeners: Use Solarium events (e.g., Solarium\Event\EventInterface) for logging or custom logic:

   $this->solarium->getEventDispatcher()->addListener('solarium.query', function ($event) {
       logger()->info('Query executed:', ['query' => $event->getQuery()->getQuery()]);
   });
   

Integration Tips

• Laravel Scout Alternative: Use Solarium for advanced search features not covered by Scout (e.g., faceting, custom scoring).
• Caching: Cache Solarium results using Laravel's cache system:

  $cacheKey = 'solr_results_' . md5($queryString);
  return cache()->remember($cacheKey, now()->addMinutes(5), function () use ($query) {
      return $this->solarium->select($query)->getResults();
  });
  

• Testing: Mock the Solarium client in tests:

  $mock = Mockery::mock('Solarium\Client');
  $mock->shouldReceive('select')->andReturn(new \Solarium\QueryType\Select\ResultSet());
  $this->app->instance('solarium.client', $mock);
  

Gotchas and Tips

Pitfalls

1. Deprecated Bundle:

   • The bundle is outdated (last release 2018). Ensure compatibility with your Solarium version (e.g., solarium/solarium ^4.0).
   • Fix: Manually patch or fork if needed. Check composer.json for required Solarium version.

2. Configuration Overrides:

   • The clients section in config is optional but required if you define multiple endpoints. Omitting it defaults to the endpoints config.
   • Fix: Always define clients if using multiple cores/endpoints:

     nelmio_solarium:
         endpoints:
             core1: { scheme: http, host: localhost, port: 8983, path: /solr, core: core1 }
             core2: { scheme: http, host: localhost, port: 8983, path: /solr, core: core2 }
         clients:
             default: [core1]
             custom: [core2]
     

3. Service Name Mismatch:

   • The service is registered as solarium.client (not nelmio_solarium.client). Double-check autowiring or manual binding.

4. Timeout Handling:

   • Default timeout (5s) may be too short for large datasets. Adjust in config:

     nelmio_solarium:
         endpoints:
             default:
                 timeout: 30  # seconds
     

Debugging

1. Enable Solarium Logging: Add to config/logging.php:

   'channels' => [
       'solarium' => [
           'driver' => 'single',
           'path' => storage_path('logs/solarium.log'),
           'level' => 'debug',
       ],
   ],
   

   Then enable logging in Solarium:

   $this->solarium->getLogger()->setLogLevel(\Solarium\Logger\LoggerInterface::LOG_DEBUG);
   

2. Query Debugging: Use the Solarium\Plugin\Debug plugin to log raw queries:

   $this->solarium->registerPlugin(new \Solarium\Plugin\Debug());
   

Extension Points

1. Custom Plugins: Register Solarium plugins (e.g., Solarium\Plugin\Highlighting) in a service provider:

   public function boot() {
       $this->app['solarium.client']->registerPlugin(new \Solarium\Plugin\Highlighting());
   }
   

2. Event Dispatcher: Extend functionality via events (e.g., Solarium\Event\QueryEvent):

   $this->app['solarium.client']->getEventDispatcher()->addListener('solarium.query', function ($event) {
       // Modify query or log
   });
   

3. Dynamic Endpoints: Override endpoints dynamically (e.g., for multi-tenant apps):

   $this->solarium->setEndpoint($this->getCurrentTenantEndpoint());
   

4. Laravel Facades: Create a facade for cleaner syntax (e.g., Solarium::query()):

   class SolariumFacade extends \Illuminate\Support\Facades\Facade {
       protected static function getFacadeAccessor() { return 'solarium.client'; }
   }