feat(filter_by): add helper to escape filter string values

README.md

@@ -18,6 +18,17 @@ Read the documentation here: [https://typesense.org/api/](https://typesense.org/
 
 Here are some examples that walk you through how to use the client: [doc/examples](examples)
 
+### Escaping filter values
+
+Use `Typesense\FilterBy::escapeString()` to safely use string values in `filter_by`:
+
+```php
+use Typesense\FilterBy;
+
+$filterValue = "The 17\" O'Conner && O`Series \n OR a || 1%2 book? (draft), [alpha]";
+$filterBy = 'tags:=' . FilterBy::escapeString($filterValue);
+```
+
 ## Compatibility
 
 | Typesense Server | typesense-php |

src/FilterBy.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Typesense;
+
+class FilterBy
+{
+    public static function escapeString(string $value): string
+    {
+        return '`' . str_replace('`', '\\`', $value) . '`';
+    }
+}

tests/Feature/FilterByTest.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace Feature;
+
+use PHPUnit\Framework\TestCase;
+use Typesense\FilterBy;
+
+class FilterByTest extends TestCase
+{
+    public function testEscapesSpecialCharactersByWrappingInBackticks(): void
+    {
+        $rawFilterValue = "The 17\" O'Conner && O`Series \n OR a || 1%2 book? (draft), [alpha]";
+
+        $escapedFilterValue = FilterBy::escapeString($rawFilterValue);
+
+        $this->assertSame(
+            "`The 17\" O'Conner && O\\`Series \n OR a || 1%2 book? (draft), [alpha]`",
+            $escapedFilterValue
+        );
+    }
+
+    public function testEscapesMultipleBackticksWithinAFilterString(): void
+    {
+        $escapedFilterValue = FilterBy::escapeString('`left` and `right`');
+
+        $this->assertSame('`\\`left\\` and \\`right\\``', $escapedFilterValue);
+    }
+}