Graphql Search Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require sitepark/atoolo-graphql-search-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Sitepark\AtooloGraphQLSearchBundle\AtooloGraphQLSearchBundle::class => ['all' => true],
   ];
   

2. First Query: Use the built-in GraphQL schema to query search results. Example:

   query Search($query: String!) {
     search(query: $query) {
       results {
         id
         title
         teaser {
           headline
           content
         }
       }
       facets {
         key
         count
       }
     }
   }
   

3. Key Documentation:

   • Bundle Documentation
   • GraphQL Queries

Implementation Patterns

Core Workflows

1. Search Query Construction

• Input Types: Use SearchInput to define queries, filters, and sorting.

  query Search($input: SearchInput!) {
    search(input: $input) {
      # Results and metadata
    }
  }
  

• Variables Example:

  {
    "input": {
      "query": "laravel",
      "filters": [
        { "field": "contentType", "value": "article" }
      ],
      "sort": { "field": "relevance" },
      "page": { "size": 10, "number": 1 }
    }
  }
  

2. Faceted Search

• Use facet fields to dynamically filter results:

  query Search($query: String!) {
    search(query: $query) {
      facets {
        key
        count
        values {
          value
          count
        }
      }
    }
  }
  

3. Teaser Customization

• Extend or override teaser resolvers (e.g., MediaTeaser, NewsTeaser) via dependency injection:

  # config/services.yaml
  Sitepark\AtooloGraphQLSearchBundle\Resolver\Teaser\MediaTeaserResolver:
    arguments:
      $customFieldResolver: '@app.service.custom_teaser_resolver'
  

4. Server-Side Execution

• Enable server-side query execution (added in v1.9.0) for complex logic:

  # config/packages/atoolo_graphql_search.yaml
  server_side_execution: true
  

5. Spatial Search

• Leverage spatial filters for geo-based queries:

  query Search($geoFilter: GeoLocatedFilter!) {
    search(filters: [$geoFilter]) {
      results {
        id
        geoLocation {
          lat
          lng
        }
      }
    }
  }
  

6. Pagination and Sorting

• Use page and sort inputs for pagination/sorting:

  query Search($input: SearchInput!) {
    search(input: $input) {
      results {
        edges {
          node {
            id
            title
          }
        }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }
  }
  

Integration Tips

Laravel-Specific Patterns

1. Service Integration:

   • Bind custom resolvers/factories to Laravel’s container:

     $this->app->bind(
         Sitepark\AtooloGraphQLSearchBundle\Resolver\Teaser\CustomTeaserResolver::class,
         App\Resolver\CustomTeaserResolver::class
     );
     

2. Event Listeners:

   • Extend search behavior via events (e.g., SearchQueryBuiltEvent):

     use Sitepark\AtooloGraphQLSearchBundle\Event\SearchQueryBuiltEvent;
     
     public function onSearchQueryBuilt(SearchQueryBuiltEvent $event) {
         $event->getQuery()->addFilter('custom_field', 'value');
     }
     

3. Configuration:

   • Override default settings in config/packages/atoolo_graphql_search.yaml:

     default_sort: 'relevance'
     min_hit_count: 3  # Added in v1.10.0
     

4. Testing:

   • Use the AtooloGraphQLSearchTestCase base class for tests:

     use Sitepark\AtooloGraphQLSearchBundle\Test\AtooloGraphQLSearchTestCase;
     
     class MySearchTest extends AtooloGraphQLSearchTestCase {
         public function testSearchQuery() {
             $this->query('
                 query { search(query: "test") { results { id } } }
             ');
         }
     }
     

Gotchas and Tips

Pitfalls

1. Deprecation Warnings:

   • symbolicImage was renamed to symbolicAsset in v1.2.0. Update queries/resolvers if using the old field.
   • headline sort criteria was removed in v1.2.0.

2. PHP Version Compatibility:

   • The bundle supports PHP 8.1–8.4, but some features (e.g., server-side execution) may require PHP 8.2+.

3. GeoJSON Edge Cases:

   • Empty GeoJSON features may cause warnings (fixed in v1.3.0). Validate spatial filters:

     input GeoLocatedFilter {
       geometry: String!
       # Ensure geometry is valid GeoJSON
     }
     

4. Caching:

   • Search results are not cached by default. Implement AtooloGraphQLSearchBundle\Event\SearchResultsEvent listeners for caching:

     public function onSearchResults(SearchResultsEvent $event) {
         Cache::put('search_' . md5($event->getQuery()), $event->getResults());
     }
     

5. Teaser Resolvers:

   • Custom teaser resolvers must implement Sitepark\AtooloGraphQLSearchBundle\Resolver\Teaser\TeaserResolverInterface. Forgetting to register them will result in missing fields.

6. Relative Date Ranges:

   • The from/to fields for relative date ranges (added in v1.9.0) require a baseOffset for accurate filtering:

     input RelativeDateRangeFilter {
       from: Int!  # Days from baseOffset
       to: Int!    # Days from baseOffset
       baseOffset: Int  # Optional (e.g., -7 for "last week")
     }
     

Debugging Tips

1. Query Analysis:

   • Use the explain field to debug search logic:

     query Search($query: String!) {
       search(query: $query) {
         explain
       }
     }
     

2. Logging:

   • Enable debug mode in config/packages/atoolo_graphql_search.yaml:

     debug: true
     

   • Logs will include raw search queries and execution details.

3. Schema Validation:

   • Validate GraphQL queries with:

     php bin/console debug:graphql
     

4. Performance:

   • Profile slow queries using Laravel’s debugbar or Xdebug. Common bottlenecks:
     • Complex spatial filters.
     • Large facet sets (limit with minHitCount).

Extension Points

1. Custom Resolvers:

   • Extend existing resolvers (e.g., AssetResolver) or create new ones:

     namespace App\Resolver;
     
     use Sitepark\AtooloGraphQLSearchBundle\Resolver\Asset\AssetResolverInterface;
     
     class CustomAssetResolver implements AssetResolverInterface {
         public function resolve($asset, array $context) {
             // Custom logic
             return [
                 'url' => $asset->getCustomUrl(),
                 'alt' => $asset->getCustomAlt(),
             ];
         }
     }
     

2. Query Modifiers:

   • Subscribe to SearchQueryBuiltEvent to modify queries dynamically:

     $event->getQuery()->addSort('custom_field', 'asc');
     

3. Teaser Factories:

   • Override teaser factories (e.g., MediaTeaserFactory) to customize teaser generation:

     namespace App\Factory;
     
     use Sitepark\AtooloGraphQLSearchBundle\Factory\Teaser\MediaTeaserFactory as BaseFactory;
     
     class CustomMediaTeaserFactory extends BaseFactory {
         protected function createTeaser(): array {
             $teaser = parent::createTeaser();
             $teaser['customField'] = 'value';
             return $teaser;
         }
     }
     

4. Context Dispatchers:

   • Extend the ContextDispatcher to add custom context data:

     namespace App\Dispatcher;
     
     use Sitepark\AtooloGraphQLSearchBundle\Dispatcher\ContextDispatcherInterface;
     
     class CustomContextDispatcher implements ContextDispatcherInterface {