Laravel Cloudsearch Laravel Package

Getting Started

First Steps

1. Installation

   composer require torann/laravel-cloudsearch
   

   Publish the config file:

   php artisan vendor:publish --provider="Torann\CloudSearch\CloudSearchServiceProvider"
   

   Update .env with your Amazon CloudSearch domain endpoint and API key (if applicable):

   CLOUDSEARCH_DOMAIN=your-domain.search.amazonaws.com
   CLOUDSEARCH_API_KEY=your-api-key
   

2. Configure a Model Add the Searchable trait to your Eloquent model:

   use Torann\CloudSearch\Searchable;
   
   class Post extends Model
   {
       use Searchable;
   
       protected $searchable = [
           'title',       // Fields to index
           'body',
           'author_name'  // Computed field (if needed)
       ];
   

3. First Indexing Trigger a manual index update (e.g., in a seeder or command):

   Post::searchable()->index();
   

   Or use a model observer to auto-index on saved/created:

   Post::observe(CloudSearchObserver::class);
   

4. Basic Search

   $results = Post::search('laravel')->get();
   // Or with pagination:
   $results = Post::search('laravel')->paginate(10);
   

Implementation Patterns

1. Workflow: Indexing Strategies

• Manual Indexing Useful for one-off updates (e.g., after bulk imports):

  Post::searchable()->index(); // Full reindex
  Post::searchable()->update(); // Incremental update
  

• Automatic Indexing Leverage observers for real-time updates:

  // app/Observers/PostObserver.php
  class PostObserver
  {
      public function saved(Post $post)
      {
          $post->searchable()->update();
      }
  }
  

• Scheduled Reindexing Use Laravel’s scheduler for periodic full reindexes:

  // app/Console/Kernel.php
  $schedule->command('cloudsearch:reindex')->daily();
  

2. Search Patterns

• Query Building Use CloudSearch’s query syntax (supports AND, OR, NOT, facets, etc.):

  $results = Post::search('laravel OR php', ['facet' => 'tags'])->get();
  

• Highlighting Results Enable highlighting in config (config/cloudsearch.php):

  'highlight' => [
      'enabled' => true,
      'fields' => ['title', 'body'],
  ],
  

  Access highlights in results:

  foreach ($results as $post) {
      dd($post->search_highlights);
  }
  

• Pagination & Sorting

  $results = Post::search('laravel')
      ->orderBy('published_at', 'desc')
      ->paginate(15);
  

3. Integration Tips

• Soft Deletes Extend the Searchable trait to handle soft deletes:

  public function searchable()
  {
      return $this->searchable()->whereNull('deleted_at');
  }
  

• Custom Fields Use searchable() method to define dynamic fields:

  protected $searchable = function () {
      return [
          'title' => $this->title,
          'full_text' => $this->title . ' ' . $this->body,
          'category' => $this->category->name,
      ];
  };
  

• Multi-Domain Search For apps with multiple CloudSearch domains, bind them dynamically:

  CloudSearch::setDomain('domain-2');
  Post::search('query')->get();
  

Gotchas and Tips

Pitfalls

1. API Key Restrictions

   • CloudSearch domains may require API keys for production. Test locally without keys but enable them in staging/prod.
   • Fix: Use CLOUDSEARCH_API_KEY in .env and ensure IAM permissions are set.

2. Field Mapping Mismatches

   • CloudSearch requires explicit field definitions. If you add a field to $searchable but forget to update the domain’s schema, searches will fail.
   • Fix: Use the cloudsearch:schema Artisan command to generate a schema file, then apply it via the AWS Console or SDK.

3. Rate Limiting

   • CloudSearch has throttling limits. Bulk operations may hit these.
   • Fix: Use index() in batches or schedule updates during off-peak hours.

4. Observer Conflicts

   • If using saved()/updated() observers, ensure searchable()->update() isn’t called recursively (e.g., if the observer triggers another save).
   • Fix: Add a guard:

     if (!$this->wasRecentlySaved) {
         $this->searchable()->update();
     }
     

Debugging Tips

1. Enable Logging Add to config/cloudsearch.php:

   'debug' => env('APP_DEBUG', false),
   

   Check logs for failed requests (e.g., storage/logs/laravel.log).

2. Raw API Responses Inspect raw CloudSearch responses for errors:

   $response = Post::search('test')->getSearchResponse();
   dd($response->toArray());
   

3. Schema Validation Use the cloudsearch:schema:dump command to verify your schema matches the domain:

   php artisan cloudsearch:schema:dump
   

Extension Points

1. Custom Search Handlers Override the search() method to add pre/post-processing:

   public function scopeSearch($query, $searchTerm)
   {
       $results = parent::search($searchTerm)->get();
       return $results->filter(fn ($item) => $item->isPublished());
   }
   

2. Webhook-Based Indexing For high-frequency updates, use CloudSearch’s webhooks instead of Laravel observers.

3. Hybrid Search Combine CloudSearch with Laravel Scout for fallback logic:

   if (CloudSearch::isHealthy()) {
       return Post::search($query)->get();
   }
   return Post::scoutSearch($query)->get();