MySearchFilter
Goal
This filter aims to allow free flow search bars that does not distinguish between each field. This Allows for the user to enter a search term that will be compared to multiple fields with OR clauses.
This is intended to replace the old ‘ApplyFilter’ method from Entitles’ repositories.
Usage
QueryParam
?search=foo bar
- Don’t support multi-value filtering
- Is accessible on every entity
- Is NOT generated by the standard filter generator (@todo review generator)
Search Workflow
The filter will attempt to match each word in the search string against multiple configured fields, including nested associations and translations.
Tokenizing Search Terms
The search string is split into individual words. Those can be called ‘Search Terms’
Example:
?search=foo bar
becomes
[“foo”, “bar”]
Empty values are discarded. This way, each word will be searched independently.
Determine Searchable Fields
The filter iterates over all fields configured in the filter declaration.
Example:
// #[ApiFilter(filterClass: MySearchFilter::class, properties: [‘id’, ‘slug’, ‘name’], arguments: [‘searchParameter’ => ‘search’])] // @todo review this
This tells the filter:
Search for each search terms in:
id
slug
name
Translation Support
If the resource implements TranslatableInterface, the filter supports searching inside translations.
Example
translations.title
Special Handling for ID Searches
If the searchable property is id, the filter supports shortcode IDs.
Example shortcode UUID:
A123
Workflow:
- The filter checks if the entity supports getShortcode()
- If the search value begins with that shortcode
- The shortcode prefix is removed
Example
?search=A123
becomes
id = 123
This allows to search using human-friendly unique identifiers.
Case-Insensitive Search
All comparisons are wrapped in LOWER().
Exemple:
- Foo Bar
- foo bar
- FOO BAR
are treated the as:
[‘foo’, ‘bar’]
Summary
✔ Global search with a single parameter
✔ Multi-word search
✔ Case-insensitive matching
✔ Nested relation search
✔ Translation support
✔ Human-readable shortcode ID support
Dev Notes
Issue #4622 - MySearchFilter Generation
Issue #4623 - Rename MySearchFilter (SearchTermsFilter)