feat: support synonym endpoint

Author: bepsvpt

src/Objects/Synonym.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Typesense\Objects;
+
+class Synonym extends TypesenseObject
+{
+    public string $id;
+
+    /**
+     * @var array<int, string>
+     */
+    public array $synonyms;
+
+    public string $root = '';
+
+    public string $locale = '';
+
+    /**
+     * @var array<int, string>
+     */
+    public array $symbols_to_index = [];
+}

src/Requests/Synonym.php

@@ -0,0 +1,84 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Typesense\Requests;
+
+use stdClass;
+use Typesense\Exceptions\Client\ResourceNotFoundException;
+use Typesense\Objects\Synonym as SynonymObject;
+
+class Synonym extends Request
+{
+    /**
+     * Create or update a synonym.
+     *
+     * @param array{
+     *     synonyms: array<int, string>,
+     *     root?: string,
+     *     locale?: string,
+     *     symbols_to_index?: array<int, string>,
+     * } $payload
+     *
+     * @see https://typesense.org/docs/latest/api/synonyms.html#create-or-update-a-synonym
+     */
+    public function upsert(string $collection, string $id, array $payload): SynonymObject
+    {
+        $path = sprintf('/collections/%s/synonyms/%s', $collection, $id);
+
+        $data = $this->send('PUT', $path, $payload);
+
+        return SynonymObject::from($data);
+    }
+
+    /**
+     * Retrieve a single synonym.
+     *
+     * @throws ResourceNotFoundException
+     *
+     * @see https://typesense.org/docs/latest/api/synonyms.html#retrieve-a-synonym
+     */
+    public function retrieve(string $collection, string $id): SynonymObject
+    {
+        $path = sprintf('/collections/%s/synonyms/%s', $collection, $id);
+
+        $data = $this->send('GET', $path);
+
+        return SynonymObject::from($data);
+    }
+
+    /**
+     * List all synonyms associated with a given collection.
+     *
+     * @return array<int, SynonymObject>
+     *
+     * @see https://typesense.org/docs/latest/api/synonyms.html#list-all-synonyms
+     */
+    public function list(string $collection): array
+    {
+        $path = sprintf('/collections/%s/synonyms', $collection);
+
+        $data = $this->send('GET', $path);
+
+        return array_map(
+            fn (stdClass $datum) => SynonymObject::from($datum),
+            $data->aliases,
+        );
+    }
+
+    /**
+     * Delete a synonym associated with a collection.
+     *
+     * @throws ResourceNotFoundException
+     *
+     * @see https://typesense.org/docs/latest/api/synonyms.html#delete-a-synonym
+     */
+    public function delete(string $collection, string $id): bool
+    {
+        $path = sprintf('/collections/%s/synonyms/%s', $collection, $id);
+
+        $data = $this->send('DELETE', $path);
+
+        return $data->id === $id;
+    }
+}

tests/Unit/SynonymTest.php

@@ -0,0 +1,104 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Typesense\Tests\Unit;
+
+use Typesense\Exceptions\Client\ResourceNotFoundException;
+
+test('it can create a multi-way synonym', function () {
+    $synonym = $this->typesense->synonym->upsert(
+        $this->collectionName,
+        $id = $this->slug(),
+        [
+            'synonyms' => $synonyms = ['apple', 'banana', 'car'],
+        ],
+    );
+
+    expect($synonym->id)->toBe($id);
+
+    expect($synonym->synonyms)->toBe($synonyms);
+
+    expect($synonym->root)->toBe('');
+});
+
+test('it can create a one-way synonym', function () {
+    $synonym = $this->typesense->synonym->upsert(
+        $this->collectionName,
+        $id = $this->slug(),
+        [
+            'root' => $root = 'dog',
+            'synonyms' => $synonyms = ['apple', 'banana', 'car'],
+        ],
+    );
+
+    expect($synonym->id)->toBe($id);
+
+    expect($synonym->synonyms)->toBe($synonyms);
+
+    expect($synonym->root)->toBe($root);
+});
+
+test('it can retrieve an existing synonym', function () {
+    $this->typesense->synonym->upsert(
+        $this->collectionName,
+        $id = $this->slug(),
+        [
+            'synonyms' => [$this->slug()],
+        ],
+    );
+
+    $synonym = $this->typesense->synonym->retrieve(
+        $this->collectionName,
+        $id,
+    );
+
+    expect($synonym->id)->toBe($id);
+});
+
+test('it can not retrieve a non-existent synonym', function () {
+    $this->typesense->synonym->retrieve(
+        $this->collectionName,
+        $this->slug(),
+    );
+})->throws(ResourceNotFoundException::class);
+
+test('it can list all synonyms', function () {
+    $synonym = $this->typesense->synonym->upsert(
+        $this->collectionName,
+        $this->slug(),
+        [
+            'synonyms' => [$this->slug()],
+        ],
+    );
+
+    $synonyms = $this->typesense->synonym->list($this->collectionName);
+
+    $ids = array_column($synonyms, 'id');
+
+    expect($synonym->id)->toBeIn($ids);
+});
+
+test('it can delete an existing synonym', function () {
+    $synonym = $this->typesense->synonym->upsert(
+        $this->collectionName,
+        $this->slug(),
+        [
+            'synonyms' => [$this->slug()],
+        ],
+    );
+
+    $deleted = $this->typesense->synonym->delete(
+        $this->collectionName,
+        $synonym->id,
+    );
+
+    expect($deleted)->toBeTrue();
+});
+
+test('it can not delete a non-existent synonym', function () {
+    $this->typesense->synonym->delete(
+        $this->collectionName,
+        $this->slug(),
+    );
+})->throws(ResourceNotFoundException::class);