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\Atoolo\GraphQLSearchBundle\AtooloGraphQLSearchBundle::class => ['all' => true],
   ];
   

2. First Use Case: Query the GraphQL API with search-specific fields. Example:

   query SearchQuery {
     search(
       query: "example"
       filters: { source: ["news"] }
       limit: 10
     ) {
       results {
         id
         headline
         teaser {
           ... on MediaTeaser {
             symbolicAsset {
               url
             }
           }
         }
       }
     }
   }
   

3. Key Documentation:

   • Bundle Documentation
   • GraphQL Queries

Implementation Patterns

Core Workflows

1. Search Query Construction:

   • Use search root field with input arguments:

     search(
       query: String!
       filters: InputFilter
       limit: Int
       offset: Int
       sort: [SortCriteria!]
       facets: [Facet!]
     )
     

   • Filters: Combine with AND/OR logic:

     filters: {
       and: [
         { source: ["news"] },
         { dateRange: { from: "2023-01-01", to: "2023-12-31" } }
       ]
     }
     

2. Teaser-Specific Resolvers:

   • Leverage teaser-specific fields (e.g., MediaTeaser, NewsTeaser):

     teaser {
       ... on MediaTeaser {
         symbolicAsset { url variant }
         kicker
       }
       ... on NewsTeaser {
         dateTime
         kicker
       }
     }
     

3. Faceted Navigation:

   • Use facets for dynamic filtering:

     facets: [
       { type: "source" },
       { type: "dateRange", from: "2023-01-01", to: "2023-12-31" }
     ]
     

4. Sorting:

   • Custom sorts via SortCriteria:

     sort: [
       { field: "relevance" },
       { field: "dateTime", direction: DESC }
     ]
     

5. Server-Side Execution:

   • Enable via config (atoolo_graphql_search.yaml):

     server_side_execution: true
     

Integration Tips

• Dependency Injection:

  • Extend search behavior via services tagged with atoolo.graphql_search.resolver:

    services:
      App\GraphQL\Search\CustomResolver:
        tags: ['atoolo.graphql_search.resolver']
    

• Custom Factories:

  • Implement SortCriteriaFactoryInterface for custom sorts:

    class CustomSortFactory implements SortCriteriaFactoryInterface {
        public function create(array $input): SortCriteria { ... }
    }
    

• URL Rewriting:

  • Use urlBasePath in queries for dynamic URL handling:

    query {
      search(query: "example", urlBasePath: "/custom-path") { ... }
    }
    

• Pagination:

  • Use limit/offset for client-side pagination or leverage cursor-based pagination if supported.

Gotchas and Tips

Pitfalls

1. Deprecation Warnings:

   • symbolicImage → Use symbolicAsset (type Asset) instead.
   • opensNewWindow → Removed in v1.1.0; use accessibilityLabel for alternatives.

2. Geo-Spatial Queries:

   • geoLocatedFilter is optional in InputFilter (not required):

     filters: {
       geoLocated: { latitude: 48.1351, longitude: 11.5820, radius: 10 }
     }
     

3. Server-Side Execution:

   • Requires atoolo/search-bundle v1.13.0+. Enable via config:

     atoolo_graphql_search:
       server_side_execution: true
     

4. Teaser Resolvers:

   • Ensure resolvers are registered as services (e.g., NewsTeaserFactory):

     services:
       Sitepark\Atoolo\GraphQLSearchBundle\Factory\NewsTeaserFactory: ~
     

5. Date Range Facets:

   • Use baseOffset for relative date ranges:

     facets: [
       { type: "dateRange", from: "-30d", to: "now", baseOffset: "2023-01-01" }
     ]
     

Debugging

1. Explain Mode:

   • Enable via explain: true in queries to analyze result scoring:

     search(query: "example", explain: true) { ... }
     

2. PHP Warnings:

   • Check for missing array keys (e.g., symbolicAsset['content']):

     // Fix: Ensure asset data structure matches expectations.
     $asset = $result->getSymbolicAsset();
     $url = $asset['content']['url'] ?? null;
     

3. Empty GeoJSON:

   • Avoid returning empty GeoJSON features by validating spatial data before queries.

Extension Points

1. Custom Sort Criteria:

   • Extend SortCriteriaFactory for domain-specific sorts (e.g., "popularity"):

     class PopularitySortFactory implements SortCriteriaFactoryInterface {
         public function create(array $input): SortCriteria {
             return new SortCriteria('popularity', SortCriteria::DIRECTION_DESC);
         }
     }
     

2. Query Templates:

   • Use queryTemplateFilter for dynamic query generation:

     filters: {
       queryTemplate: { template: "custom_template", params: { tag: "news" } }
     }
     

3. Context Dispatchers:

   • Override context logic via ContextDispatcherInterface:

     class CustomContextDispatcher implements ContextDispatcherInterface {
         public function dispatch(Context $context): Context { ... }
     }
     

4. Static Images:

   • Use staticImage for non-dynamic assets:

     teaser {
       ... on MediaTeaser {
         staticImage { url }
       }
     }
     

Configuration Quirks

1. Min Hit Count:

   • Filter facets by minimum hits:

     atoolo_graphql_search:
       min_hit_count: 3  # Default: 0
     

2. Base Offsets:

   • Required for relative date ranges (e.g., from: "-30d" needs baseOffset).

3. Type Aliases:

   • Use TeaserFeature for teaser-specific actions (replaced actions in v1.7.0).

Performance Tips

1. Server-Side Execution:

   • Reduces client-side processing; enable for large datasets.

2. Facet Limiting:

   • Restrict facets to essential types to avoid over-fetching:

     facets: [{ type: "source", limit: 5 }]
     

3. Pagination:

   • Prefer limit/offset over fetching all results for large datasets.

4. Caching:

   • Leverage Symfony’s cache system for repeated queries:

     atoolo_graphql_search:
       cache: cache.app