feat(stemming): add stemming dictionary management support

- add `Stemming`, `StemmingDictionaries`, and `StemmingDictionary` classes
- implement dictionary upsert and retrieve operations
- add client support for stemming feature
- add tests for dictionary operations

Author: tharropoulos

src/Client.php

@@ -75,6 +75,11 @@ class Client
      */
     public Analytics $analytics;
 
+    /**
+     * @var Stemming
+     */
+    public Stemming $stemming;
+
     /**
      * @var Conversations
      */
@@ -108,6 +113,7 @@ public function __construct(array $config)
         $this->multiSearch   = new MultiSearch($this->apiCall);
         $this->presets       = new Presets($this->apiCall);
         $this->analytics     = new Analytics($this->apiCall);
+        $this->stemming     = new Stemming($this->apiCall);
         $this->conversations = new Conversations($this->apiCall);
     }
 
@@ -199,6 +205,14 @@ public function getAnalytics(): Analytics
         return $this->analytics;
     }
 
+    /**
+     * @return Stemming
+     */
+    public function getStemming(): Stemming
+    {
+        return $this->stemming;
+    }
+
     /**
      * @return Conversations
      */

src/Stemming.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace Typesense;
+
+class Stemming
+{
+    const RESOURCE_PATH = '/stemming';
+
+    private ApiCall $apiCall;
+
+    private StemmingDictionaries $typesenseDictionaries;
+
+
+    public function __construct(ApiCall $apiCall)
+    {
+        $this->apiCall = $apiCall;
+    }
+
+    public function dictionaries()
+    {
+        if (!isset($this->typesenseDictionaries)) {
+            $this->typesenseDictionaries = new StemmingDictionaries($this->apiCall);
+        }
+        return $this->typesenseDictionaries;
+    }
+}

src/StemmingDictionaries.php

@@ -0,0 +1,93 @@
+<?php
+
+namespace Typesense;
+
+class StemmingDictionaries implements \ArrayAccess
+{
+    const RESOURCE_PATH = '/stemming/dictionaries';
+
+    private ApiCall $apiCall;
+    private $typesenseDictionaries = [];
+
+    public function __construct(ApiCall $apiCall)
+    {
+        $this->apiCall = $apiCall;
+    }
+
+    public function __get($id)
+    {
+        if (!isset($this->typesenseDictionaries[$id])) {
+            $this->typesenseDictionaries[$id] = new StemmingDictionary($id, $this->apiCall);
+        }
+        return $this->typesenseDictionaries[$id];
+    }
+
+    public function upsert($id, $wordRootCombinations)
+    {
+        $dictionaryInJSONLFormat = is_array($wordRootCombinations) ? implode(
+            "\n",
+            array_map(
+                static fn(array $wordRootCombo) => json_encode($wordRootCombo, JSON_THROW_ON_ERROR),
+                $wordRootCombinations
+            )
+        ) : $wordRootCombinations;
+
+        $resultsInJSONLFormat = $this->apiCall->post($this->endpoint_path("import"), $dictionaryInJSONLFormat, false, ["id" => $id]);
+
+        return is_array($wordRootCombinations) ? array_map(
+            static function ($item) {
+                return json_decode($item, true, 512, JSON_THROW_ON_ERROR);
+            },
+            array_filter(
+                explode("\n", $resultsInJSONLFormat),
+                'strlen'
+            )
+        ) : $resultsInJSONLFormat;
+    }
+
+    public function retrieve()
+    {
+        return $this->apiCall->get(StemmingDictionaries::RESOURCE_PATH, []);
+    }
+
+    private function endpoint_path($operation = null)
+    {
+        return $operation === null ? self::RESOURCE_PATH : self::RESOURCE_PATH . "/" . encodeURIComponent($operation);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function offsetExists($offset): bool
+    {
+        return isset($this->typesenseDictionaries[$offset]);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function offsetGet($offset): StemmingDictionary
+    {
+        if (!isset($this->typesenseDictionaries[$offset])) {
+            $this->typesenseDictionaries[$offset] = new StemmingDictionary($offset, $this->apiCall);
+        }
+
+        return $this->typesenseDictionaries[$offset];
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function offsetSet($offset, $value): void
+    {
+        $this->typesenseDictionaries[$offset] = $value;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function offsetUnset($offset): void
+    {
+        unset($this->typesenseDictionaries[$offset]);
+    }
+}

src/StemmingDictionary.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Typesense;
+
+class StemmingDictionary
+{
+    private $id;
+    private ApiCall $apiCall;
+
+    public function __construct(string $id, ApiCall $apiCall)
+    {
+        $this->id = $id;
+        $this->apiCall  = $apiCall;
+    }
+
+    public function retrieve()
+    {
+        return $this->apiCall->get($this->endpointPath(), []);
+    }
+
+    private function endpointPath()
+    {
+        return StemmingDictionaries::RESOURCE_PATH . '/' . encodeURIComponent($this->id);
+    }
+}

tests/Feature/StemmingDictionariesTest.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace Feature;
+
+use Tests\TestCase;
+
+class StemmingDictionariesTest extends TestCase
+{
+    private $dictionaryId = 'test_dictionary';
+
+    private $dictionary = [
+            ["root" => "exampleRoot1", "word" => "exampleWord1"],
+            ["root" => "exampleRoot2", "word" => "exampleWord2"]
+    ];
+
+    private $dictionaryUpsertResponse = null;
+
+    public function testCanUpsertADictionary(): void
+    {
+        $this->dictionaryUpsertResponse = $this->client()->stemming->dictionaries()->upsert($this->dictionaryId, $this->dictionary);
+        $this->assertEquals($this->dictionary, $this->dictionaryUpsertResponse);
+    }
+
+    public function testCanRetrieveADictionary(): void
+    {
+        $returnData = $this->client()->stemming->dictionaries()[$this->dictionaryId]->retrieve();
+        $this->assertEquals($returnData['id'], $this->dictionaryId);
+    }
+
+
+    public function testCanRetrieveAllRules(): void
+    {
+        $returnData = $this->client()->stemming->dictionaries()->retrieve();
+        $this->assertCount(1, $returnData['dictionaries']);
+        $this->assertEquals($returnData['dictionaries'][0], $this->dictionaryId);
+    }
+}