Search Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Solr Integration: The bundle is designed for Apache Solr, a high-performance search platform, which aligns well with Laravel applications requiring advanced search capabilities (e.g., faceted search, geospatial queries, spellcheck, and full-text indexing).
• Resource-Based Indexing: Leverages atoolo/resource-bundle for indexing structured resources (e.g., CMS content, products, or custom entities), making it suitable for Laravel apps with doctrine/eloquent models or API-driven data.
• Symfony Compatibility: Built for Symfony 6/7, but integrates seamlessly with Laravel via Symfony’s DI container (via symfony/dependency-injection or symfony/http-kernel). Requires minimal Laravel-specific adaptations (e.g., service aliasing).
• Event-Driven Indexing: Supports background indexing (via CLI commands or queues) and real-time updates, critical for Laravel apps needing scalable search without blocking HTTP requests.

Integration Feasibility

• Core Dependencies:
  • Solr Client: Requires a Solr instance (self-hosted or cloud-based like SolrCloud). Laravel’s solarium/solarium or apache/solr-client-php can bridge gaps if needed.
  • Resource Bundle: Tightly coupled with atoolo/resource-bundle (v1.7+). If your Laravel app uses custom entities, you’ll need to adapt resource mappings or extend the bundle.
  • PHP 8.1+: Compatible with Laravel’s supported PHP versions (8.1–8.4).
• Laravel-Specific Considerations:
  • Service Container: Laravel’s DI container is compatible, but you may need to override Symfony’s autowiring for some services (e.g., SearchQueryDenormalizer).
  • Event System: Laravel’s events can trigger indexing via listeners or queues (e.g., resource.updated → IndexerCommand).
  • Routing: Search endpoints (e.g., /search) can be integrated via Laravel’s route middleware or API resources.

Technical Risk

Key Questions

1. Solr Infrastructure:
   • Is Solr already deployed, or will this require new infrastructure? What’s the scaling plan (e.g., sharding, replication)?
2. Data Model Alignment:
   • How do your Laravel models/entities map to atoolo/resource-bundle resources? Will you need custom Resource implementations?
3. Indexing Strategy:
   • Should indexing be real-time (event-driven) or batch (scheduled)? How will you handle large datasets?
4. Search UI/UX:
   • Will you use the bundle’s built-in search endpoints, or integrate results into existing Laravel APIs/views?
5. Fallback Mechanisms:
   • What’s the plan if Solr is unavailable? (e.g., database fallback, cached results)
6. Localization:
   • Does your app support multi-language content? The bundle handles locale-specific indexing (e.g., update with locale in v1.13.0).
7. Security:
   • How will you handle protected resources (e.g., ACLs via auth-groups) in Solr? The bundle supports this via include_groups.

Integration Approach

Stack Fit

• Laravel Core:
  • Eloquent/Models: Map to ResourceBundle entities or use DTOs for indexing.
  • Events/Listeners: Trigger indexing on created, updated, or deleted events.
  • Queues: Offload indexing to atoolo-search-bundle's CLI commands or custom queue jobs.
• Symfony Integration:
  • Use symfony/flex or symfony/dependency-injection to bridge Laravel’s container.
  • Override Symfony’s Bundle class with a Laravel ServiceProvider for autoloading.
• Solr:
  • Configure Solr schema (managed-schema) to match IndexSchema2xDocument fields (e.g., sp_startletter, sp_sortvalue).
  • Use Solr’s dynamic fields for flexible indexing if your Laravel models evolve.

Migration Path

1. Phase 1: Setup

   • Install Solr (e.g., Docker, AWS OpenSearch, or self-hosted).
   • Add bundle to composer.json:

     composer require sitepark/atoolo-search-bundle
     

   • Publish bundle config (php artisan vendor:publish --tag=atoolo-search-config).
   • Configure solr.yml with your Solr core/collection URL.

2. Phase 2: Resource Mapping

   • Extend ResourceBundle to map Laravel models to Resource objects.
   • Example:

     // app/Resources/MyModelResource.php
     use Sitepark\Atoolo\ResourceBundle\Resource;
     
     class MyModelResource extends Resource {
         public function getIndexableData(): array {
             return [
                 'title' => $this->model->title,
                 'content' => $this->model->body,
                 'sp_startletter' => $this->model->title[0] ?? '',
             ];
         }
     }
     

3. Phase 3: Indexing

   • Initial Index: Use the CLI command:

     php artisan atoolo:search:index --resource=MyModelResource --batch-size=100
     

   • Real-Time Indexing: Add a listener:

     // app/Listeners/IndexOnUpdate.php
     public function handle(object $event) {
         Indexer::indexResource($event->model->toResource());
     }
     

4. Phase 4: Search Integration

   • Create a Laravel route/controller to handle search queries:

     // routes/web.php
     Route::get('/search', [SearchController::class, 'index']);
     

   • Use the bundle’s SearchQueryDenormalizer to build Solr queries:

     $query = new SearchQuery();
     $query->addFilter(new TextFilter('title', 'laravel'));
     $results = $searchClient->search($query);
     

Compatibility

• Laravel Versions: Tested with PHP 8.1–8.4; compatible with Laravel 10/11.
• Solr Versions: Requires Solr 8.x/9.x (check solarium/solarium compatibility).
• Database: No direct DB dependency, but indexed data must align with Solr schema.
• Caching: Leverage Laravel’s cache (e.g., cache:tag) for query results if needed.

Sequencing

1. Pre-requisites:
   • Solr instance up and running.
   • Laravel models/resources mapped to atoolo/resource-bundle.
2. Core Integration:
   • Install bundle → configure Solr → publish config.
3. Indexing:
   • Initial bulk index → real-time indexing via events/queues.
4. Search:
   • Build query endpoints → integrate results into UI/API.
5. Optimization:
   • Tune Solr schema/queries → monitor performance.

Operational Impact

Maintenance

• Solr Management:
  • Regular schema updates (e.g., adding new fields like sp_startletter).
  • Monitor Solr logs for indexing errors or performance degradation.
• Bundle Updates:
  • Follow atoolo/search-bundle releases (e.g., v1.14.0’s minHitCount feature).
  • Test upgrades in staging; some Symfony-specific changes may require Laravel adaptations.
• Dependency Updates:
  • atoolo/resource-bundle (v1.7+) and solarium/solarium may need version pinning.

Support

• Debugging:
  • Use Solr’s admin UI (/solr/#/) to inspect indexes and queries.
  • Enable Laravel logging for Sitepark\Atoolo\SearchBundle events.
• Common Issues:
  • Indexing Failures: Check Solr schema mismatches or resource mapping errors.
  • Query Performance: Optimize Solr filters/facets (e.g., avoid * queries).
  • Locale Issues: Ensure update with locale (v1.13.0) is configured for multi-language apps.
• Community:
  • Limited stars (