Header-Driven Filter Mode

Overview

Dynamically select filter engines per request using HTTP headers. This enables:

• Different filtering strategies for various clients (mobile/web)
• A/B testing of filter engines
• Gradual migration between engines

// Example: Force using Tree engine
curl -H "X-Filter-Mode: tree" https://api.example.com/products

Configuration

Enable Feature

'header_driven_mode' => [
  'enabled' => true, // Enable/disable entire feature
  'header_name' => 'X-Filter-Mode', // Customize header name
  'fallback_strategy' => 'default' // 'default' or 'error'
]

Engine Whitelisting

'allowed_engines' => ['dynamic', 'tree'], // Empty array allows all

Name Aliasing

'engine_map' => [
  'simple' => 'ruleset',
  'advanced' => 'dynamic'
],
// Use: -H "X-Filter-Mode: simple" => ruleset

---

Usage Guide

Basic Implementation

1. Add header to request:

GET /api/users X-Filter-Mode: tree

1. Server will:
   • Validate header value
   • Map aliases if configured
   • Apply specified engine

---

Error Handling

When fallback_strategy = 'error':

{
  "error": "Invalid filter engine",
  "allowed": ["dynamic", "tree"],
  "aliases": { "simple": "ruleset" }
}

Per-Query Selection

Filterable::create()->filter(Product::query())->withHeaderDrivenMode([...]);

Method Reference

withHeaderDrivenMode(array $config)

Option	Type	Default	Description
header_name	string	config value	The HTTP header name that will be checked for engine selection.
allowed_engines	array	config value	List of engine names that can be specified in the header.
engine_map	array	config value	Maps header values to actual engine names.
fallback_strategy	string	config value	Determines behavior when an invalid engine is specified

Best Practices

1. Security: Always whitelist engines in production

'allowed_engines' => ['dynamic', 'tree']

Security Considerations

• Always whitelist allowed engines in production
• Consider rate limiting header modifications
• Disable in stateless environments where headers can't be trusted