Header-Driven Filter Mode
About 253 wordsLess than 1 minute
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/productsConfiguration
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 allName Aliasing
'engine_map' => [
'simple' => 'ruleset',
'advanced' => 'dynamic'
],
// Use: -H "X-Filter-Mode: simple" => rulesetUsage Guide
Basic Implementation
- Add header to request:
GET /api/users X-Filter-Mode: tree- 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
- 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