Search Helper Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ursusarctosua/search-helper
   

   Add the service provider to config/app.php:

   Ursusarctosua\SearchHelper\SearchHelperServiceProvider::class,
   

2. Basic Usage Inject the SearchHelper class into your controller/service:

   use Ursusarctosua\SearchHelper\SearchHelper;
   
   public function __construct(private SearchHelper $searchHelper) {}
   

3. First Query Define a DTO (Data Transfer Object) for your entity filters (e.g., UserSearchDTO):

   class UserSearchDTO {
       public ?string $name;
       public ?int $age;
       public ?string $email;
   }
   

   Use it in a repository/service:

   $query = $this->searchHelper->applyFilters(
       User::class,
       new UserSearchDTO($request->all())
   );
   $results = $query->get();
   

Implementation Patterns

1. DTO-Driven Filtering

• Pattern: Use DTOs to encapsulate query parameters.

  class ProductSearchDTO {
      public ?string $name;
      public ?string $category;
      public ?int $minPrice;
      public ?int $maxPrice;
  }
  

• Benefit: Clean separation of concerns, type safety, and easy validation.

2. Repository Integration

• Pattern: Extend a base repository or trait to standardize search logic.

  class UserRepository {
      public function search(UserSearchDTO $dto) {
          return $this->searchHelper->applyFilters(User::class, $dto)->get();
      }
  }
  

• Tip: Use dependency injection to inject SearchHelper into repositories.

3. Dynamic Query Building

• Pattern: Chain filters dynamically (e.g., for API pagination/sorting).

  $query = $this->searchHelper->applyFilters(User::class, $dto);
  $query = $this->searchHelper->applySort($query, $request->get('sort'));
  $query = $this->searchHelper->applyPagination($query, $request->get('page'));
  

4. Custom Filter Rules

• Pattern: Register custom filter rules for complex logic.

  $this->searchHelper->addFilterRule('age', function ($query, $value) {
      return $query->where('age', '>=', $value);
  });
  

5. API Resource Integration

• Pattern: Use with Laravel API Resources for consistent responses.

  return UserResource::collection(
      $this->searchHelper->applyFilters(User::class, $dto)->paginate()
  );
  

Gotchas and Tips

Common Pitfalls

1. Case Sensitivity in Filters

   • By default, string filters may be case-sensitive. Use str_contains or lower() for case-insensitive searches:

     $this->searchHelper->addFilterRule('name', function ($query, $value) {
         return $query->where('name', 'LIKE', "%{$value}%");
     });
     

2. Null Handling

   • Unset or null DTO properties may break queries. Explicitly filter them:

     $dto = new UserSearchDTO($request->all());
     $dto->name = $dto->name ?? null; // Ensure null instead of empty string
     

3. Performance with Large Datasets

   • Avoid LIKE on indexed columns (e.g., WHERE name LIKE '%term%'). Use full-text search or prefix matching:

     $query->where('name', 'LIKE', "{$value}%");
     

4. Caching Query Builders

   • Doctrine query builders are not cacheable. Reuse the same builder instance if possible:

     $query = $this->searchHelper->applyFilters(User::class, $dto);
     // Reuse $query for multiple operations (e.g., count + paginate).
     

Debugging Tips

• Log Generated SQL:

  $query = $this->searchHelper->applyFilters(User::class, $dto);
  \DB::enableQueryLog();
  $results = $query->get();
  dd(\DB::getQueryLog());
  

• Validate DTOs Early: Use Laravel’s validation or a library like spatie/laravel-data to validate DTOs before passing them to SearchHelper.

Extension Points

1. Custom Filter Rules: Override or extend default rules via service provider:

   $this->app->make('Ursusarctosua\SearchHelper\SearchHelper')->addFilterRule('custom_field', ...);
   

2. Integration with Eloquent: If using Eloquent, wrap Doctrine queries:

   $query = $this->searchHelper->applyFilters(User::class, $dto);
   return User::fromQuery($query)->get();
   

3. Localization: For multilingual apps, add locale-aware filters:

   $this->searchHelper->addFilterRule('name', function ($query, $value) {
       return $query->where('name', 'LIKE', "%" . trans('search.term') . "%");
   });
   

4. Testing: Mock SearchHelper in tests:

   $mockHelper = Mockery::mock(SearchHelper::class);
   $mockHelper->shouldReceive('applyFilters')
              ->once()
              ->andReturn(User::query()->where('active', true));