From ed6cfa0b14c09154620a297d978f5163a7e72386 Mon Sep 17 00:00:00 2001
From: Fanis Tharropoulos <ftharropoulos@gmail.com>
Date: Mon, 25 May 2026 14:56:13 +0300
Subject: [PATCH 01/21] docs(client): add phpdoc for client resources

---
 src/Client.php | 146 ++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 145 insertions(+), 1 deletion(-)

diff --git a/src/Client.php b/src/Client.php
index db8c3b8a..404f28a5 100644
--- a/src/Client.php
+++ b/src/Client.php
@@ -7,7 +7,9 @@
 
 include('utils/utils.php');
 /**
- * Class Client
+ * Typesense client for indexing, searching, and managing collections.
+ *
+ * @see https://typesense.org/docs/latest/api/
  *
  * @package \Typesense
  * @date    4/5/20
@@ -21,86 +23,228 @@ class Client
     private Configuration $config;
 
     /**
+     * Access the collections resource. Use as a method-style endpoint to list or create collections,
+     * or as an array to access a single collection by name.
+     *
+     * @example
+     * $client->collections->create(['name' => 'products', 'fields' => [['name' => 'title', 'type' => 'string']]])
+     * @example
+     * $client->collections['products']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/collections.html
+     *
      * @var Collections
      */
     public Collections $collections;
 
     /**
+     * Manage stopwords sets used at query time.
+     *
+     * @example
+     * $client->stopwords->put(['name' => 'en', 'stopwords' => ['a', 'the']])
+     *
+     * @see https://typesense.org/docs/latest/api/stopwords.html
+     *
      * @var Stopwords
      */
     public Stopwords $stopwords;
 
     /**
+     * Access the aliases resource. Use it to upsert or list aliases, or as an array
+     * to access a single alias by name.
+     *
+     * @example
+     * $client->aliases->upsert('my-alias', ['collection_name' => 'products'])
+     * @example
+     * $client->aliases['my-alias']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/collection-alias.html
+     *
      * @var Aliases
      */
     public Aliases $aliases;
 
     /**
+     * Access the API keys resource. Use it to create or list keys, or as an array
+     * to access a single key by ID.
+     *
+     * @example
+     * $client->keys->create(['description' => 'Search-only key', 'actions' => ['documents:search'], 'collections' => ['*']])
+     * @example
+     * $client->keys[1]->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/api-keys.html
+     *
      * @var Keys
      */
     public Keys $keys;
 
     /**
+     * Retrieve server version and state information.
+     *
+     * @example
+     * $client->debug->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/cluster-operations.html#debug
+     *
      * @var Debug
      */
     public Debug $debug;
 
     /**
+     * Get current RAM, CPU, Disk & Network usage metrics.
+     *
+     * @example
+     * $client->metrics->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/cluster-operations.html
+     *
      * @var Metrics
      */
     public Metrics $metrics;
 
     /**
+     * Checks if Typesense server is ready to accept requests.
+     *
+     * @example
+     * $client->health->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/cluster-operations.html#health
+     *
      * @var Health
      */
     public Health $health;
 
     /**
+     * Cluster operations: snapshots, voting, cache, on-disk compaction, slow request log.
+     *
+     * @example
+     * $client->operations->perform('snapshot', ['snapshot_path' => '/tmp/snap'])
+     *
+     * @see https://typesense.org/docs/latest/api/cluster-operations.html
+     *
      * @var Operations
      */
     public Operations $operations;
 
     /**
+     * Send multiple search requests in a single HTTP request.
+     *
+     * @example
+     * $client->multiSearch->perform(['searches' => [['collection' => 'products', 'q' => '*']]])
+     *
+     * @see https://typesense.org/docs/latest/api/documents.html#federated-multi-search
+     *
      * @var MultiSearch
      */
     public MultiSearch $multiSearch;
 
     /**
+     * Access the presets resource. Use it to upsert or list presets, or as an array
+     * to access a single preset by name.
+     *
+     * @example
+     * $client->presets->upsert('listing_view', ['value' => ['q' => '*']])
+     * @example
+     * $client->presets['listing_view']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/search.html#presets
+     *
      * @var Presets
      */
     public Presets $presets;
 
     /**
+     * Legacy v1 analytics API for rules and events.
+     *
+     * @example
+     * $client->analyticsV1->rules()->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
+     *
      * @var AnalyticsV1
      */
     public AnalyticsV1 $analyticsV1;
 
     /**
+     * Manage analytics rules and events.
+     *
+     * @example
+     * $client->analytics->rules()->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
+     *
      * @var Analytics
      */
     public Analytics $analytics;
 
     /**
+     * Manage stemming dictionaries.
+     *
+     * @example
+     * $client->stemming->dictionaries()->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/stemming.html
+     *
      * @var Stemming
      */
     public Stemming $stemming;
 
     /**
+     * Access the conversation models resource and individual conversations.
+     *
+     * @example
+     * $client->conversations->typesenseModels->retrieve()
+     * @example
+     * $client->conversations['conv-1']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/conversational-search-rag.html
+     *
      * @var Conversations
      */
     public Conversations $conversations;
 
     /**
+     * Access the NL search models resource. Use it to create or list models, or as an array
+     * to access a single model by ID.
+     *
+     * @example
+     * $client->nlSearchModels->create(['model_name' => 'openai/gpt-4'])
+     * @example
+     * $client->nlSearchModels['model-1']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/natural-language-search.html
+     *
      * @var NLSearchModels
      */
     public NLSearchModels $nlSearchModels;
 
     /**
+     * Access the synonym sets resource. Use it to upsert or list sets, or as an array
+     * to access a single set by name.
+     *
+     * @example
+     * $client->synonymSets->retrieve()
+     * @example
+     * $client->synonymSets['my-set']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/synonyms.html
+     *
      * @var SynonymSets
      */
     public SynonymSets $synonymSets;
 
     /**
+     * Access the curation sets resource. Use it to upsert or list sets, or as an array
+     * to access a single set by name.
+     *
+     * @example
+     * $client->curationSets->retrieve()
+     * @example
+     * $client->curationSets['my-set']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/curation.html
+     *
      * @var CurationSets
      */
     public CurationSets $curationSets;

From 3bba03cd7589b223c103335ec5d5ea3f66ab89cd Mon Sep 17 00:00:00 2001
From: Fanis Tharropoulos <ftharropoulos@gmail.com>
Date: Mon, 25 May 2026 14:56:33 +0300
Subject: [PATCH 02/21] docs(debug): add phpdoc for debug class methods

---
 src/Debug.php | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/Debug.php b/src/Debug.php
index c6987387..a1e38afc 100644
--- a/src/Debug.php
+++ b/src/Debug.php
@@ -31,6 +31,13 @@ public function __construct(ApiCall $apiCall)
     }
 
     /**
+     * Retrieve server version and state information.
+     *
+     * @example
+     * $client->debug->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/cluster-operations.html#debug
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */

From 4ac3b431a012a1067839ebb30d7c72e5d1f86e2f Mon Sep 17 00:00:00 2001
From: Fanis Tharropoulos <ftharropoulos@gmail.com>
Date: Mon, 25 May 2026 14:56:33 +0300
Subject: [PATCH 03/21] docs(metrics): add phpdoc for metrics class methods

---
 src/Metrics.php | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/Metrics.php b/src/Metrics.php
index fb3c8b56..94ebd0f9 100644
--- a/src/Metrics.php
+++ b/src/Metrics.php
@@ -31,6 +31,13 @@ public function __construct(ApiCall $apiCall)
     }
 
     /**
+     * Get current RAM, CPU, Disk & Network usage metrics.
+     *
+     * @example
+     * $client->metrics->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/cluster-operations.html
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */

From d5cb20c259249e0023faaa26b2a072e54db4d604 Mon Sep 17 00:00:00 2001
From: Fanis Tharropoulos <ftharropoulos@gmail.com>
Date: Mon, 25 May 2026 14:56:33 +0300
Subject: [PATCH 04/21] docs(health): add phpdoc for health class methods

---
 src/Health.php | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/Health.php b/src/Health.php
index f0db09ed..b1607883 100644
--- a/src/Health.php
+++ b/src/Health.php
@@ -31,6 +31,13 @@ public function __construct(ApiCall $apiCall)
     }
 
     /**
+     * Checks if Typesense server is ready to accept requests.
+     *
+     * @example
+     * $client->health->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/cluster-operations.html#health
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */

From c9bbc6b48bc7f682c5c78f20f58f9fc6d4cc96d3 Mon Sep 17 00:00:00 2001
From: Fanis Tharropoulos <ftharropoulos@gmail.com>
Date: Mon, 25 May 2026 14:56:33 +0300
Subject: [PATCH 05/21] docs(operations): add phpdoc for operations class
 methods

---
 src/Operations.php | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/src/Operations.php b/src/Operations.php
index ea24fe94..b0d8bcfb 100644
--- a/src/Operations.php
+++ b/src/Operations.php
@@ -30,6 +30,13 @@ public function __construct(ApiCall $apiCall)
     }
 
     /**
+     * Perform a cluster operation: snapshot, vote, cache/clear, db/compact, or a custom path.
+     *
+     * @example
+     * $client->operations->perform('snapshot', ['snapshot_path' => '/tmp/snap'])
+     *
+     * @see https://typesense.org/docs/latest/api/cluster-operations.html
+     *
      * @param string $operationName
      * @param array $queryParameters
      *
@@ -47,6 +54,13 @@ public function perform(string $operationName, array $queryParameters = []): arr
     }
 
     /**
+     * Get the status of in-progress schema change operations.
+     *
+     * @example
+     * $client->operations->getSchemaChangeStatus()
+     *
+     * @see https://typesense.org/docs/latest/api/cluster-operations.html
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */

From a7edf357df0865a7aca0cfc2fa2971d132db0aa0 Mon Sep 17 00:00:00 2001
From: Fanis Tharropoulos <ftharropoulos@gmail.com>
Date: Mon, 25 May 2026 14:56:34 +0300
Subject: [PATCH 06/21] docs(multi-search): add phpdoc for multi-search class
 methods

---
 src/MultiSearch.php | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/src/MultiSearch.php b/src/MultiSearch.php
index 2bcf09fd..a4aa1b8c 100644
--- a/src/MultiSearch.php
+++ b/src/MultiSearch.php
@@ -30,6 +30,15 @@ public function __construct(ApiCall $apiCall)
     }
 
     /**
+     * Send multiple search requests in a single HTTP request. Pass `union: true` to merge results, or omit it to receive a `results` array.
+     *
+     * @example
+     * $client->multiSearch->perform(['searches' => [['collection' => 'products', 'q' => '*']]])
+     * @example
+     * $client->multiSearch->perform(['union' => true, 'searches' => [['collection' => 'products', 'q' => '*']]])
+     *
+     * @see https://typesense.org/docs/latest/api/documents.html#federated-multi-search
+     *
      * @param array $searches
      * @param array $queryParameters
      *

From 85842d3c2bad648dc84fa4499a956055ed13cb68 Mon Sep 17 00:00:00 2001
From: Fanis Tharropoulos <ftharropoulos@gmail.com>
Date: Mon, 25 May 2026 14:56:43 +0300
Subject: [PATCH 07/21] docs(analytics): add phpdoc for analytics class methods

---
 src/Analytics.php | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/src/Analytics.php b/src/Analytics.php
index 4591de04..e91fc42d 100644
--- a/src/Analytics.php
+++ b/src/Analytics.php
@@ -17,6 +17,17 @@ public function __construct(ApiCall $apiCall)
         $this->apiCall = $apiCall;
     }
 
+    /**
+     * Access the analytics rules resource. Use as a method-style endpoint to list or create rules,
+     * or chain `[$id]` on the returned object to access a single rule.
+     *
+     * @example
+     * $client->analytics->rules()->retrieve()
+     * @example
+     * $client->analytics->rules()['rule-1']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
+     */
     public function rules()
     {
         if (!isset($this->rules)) {
@@ -25,6 +36,14 @@ public function rules()
         return $this->rules;
     }
 
+    /**
+     * Access the analytics events resource to send analytics events.
+     *
+     * @example
+     * $client->analytics->events()->create(['type' => 'click', 'name' => 'products_click', 'data' => []])
+     *
+     * @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
+     */
     public function events()
     {
         if (!isset($this->events)) {

From 5e69222bd6365047227c26fcc1d2d1dc350313ad Mon Sep 17 00:00:00 2001
From: Fanis Tharropoulos <ftharropoulos@gmail.com>
Date: Mon, 25 May 2026 14:56:43 +0300
Subject: [PATCH 08/21] docs(analytics-rules): add phpdoc for analytics rules
 and events class methods

---
 src/AnalyticsEvents.php | 18 ++++++++++++++----
 src/AnalyticsRule.php   | 27 +++++++++++++++++++++------
 src/AnalyticsRules.php  | 18 ++++++++++++++----
 3 files changed, 49 insertions(+), 14 deletions(-)

diff --git a/src/AnalyticsEvents.php b/src/AnalyticsEvents.php
index 47e57465..6deadc10 100644
--- a/src/AnalyticsEvents.php
+++ b/src/AnalyticsEvents.php
@@ -29,8 +29,13 @@ public function __construct(ApiCall $apiCall)
     }
 
     /**
-     * Create an analytics event
-     * 
+     * Submit a single analytics event. The event must correspond to an existing analytics rule by name.
+     *
+     * @example
+     * $client->analytics->events()->create(['type' => 'click', 'name' => 'products_click', 'data' => []])
+     *
+     * @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
+     *
      * @param array $params Event parameters including name, event_type, and data
      * @return array Response from the API
      * @throws TypesenseClientError|HttpClientException
@@ -41,8 +46,13 @@ public function create(array $params)
     }
 
     /**
-     * Retrieve analytics events
-     * 
+     * Retrieve the most recent events for a user and rule.
+     *
+     * @example
+     * $client->analytics->events()->retrieve(['user_id' => 'u1', 'name' => 'products_click', 'n' => 10])
+     *
+     * @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
+     *
      * @param array $params Query parameters
      * @return array Response from the API
      */
diff --git a/src/AnalyticsRule.php b/src/AnalyticsRule.php
index 2c303960..847ad1f1 100644
--- a/src/AnalyticsRule.php
+++ b/src/AnalyticsRule.php
@@ -14,8 +14,13 @@ public function __construct(string $ruleName, ApiCall $apiCall)
     }
 
     /**
-     * Retrieve a specific analytics rule
-     * 
+     * Retrieve the details of an analytics rule, given its name.
+     *
+     * @example
+     * $client->analytics->rules()['rule-1']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
+     *
      * @return array Response from the API
      */
     public function retrieve()
@@ -24,8 +29,13 @@ public function retrieve()
     }
 
     /**
-     * Delete a specific analytics rule
-     * 
+     * Permanently deletes an analytics rule, given its name.
+     *
+     * @example
+     * $client->analytics->rules()['rule-1']->delete()
+     *
+     * @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
+     *
      * @return array Response from the API
      */
     public function delete()
@@ -34,8 +44,13 @@ public function delete()
     }
 
     /**
-     * Update a specific analytics rule
-     * 
+     * Upserts an analytics rule with the given name.
+     *
+     * @example
+     * $client->analytics->rules()['rule-1']->update(['type' => 'popular_queries', 'params' => []])
+     *
+     * @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
+     *
      * @param array $params Rule parameters
      * @return array Response from the API
      */
diff --git a/src/AnalyticsRules.php b/src/AnalyticsRules.php
index 4e80a07d..ca8ca9b9 100644
--- a/src/AnalyticsRules.php
+++ b/src/AnalyticsRules.php
@@ -19,8 +19,13 @@ public function __construct(ApiCall $apiCall)
     }
 
     /**
-     * Create multiple analytics rules
-     * 
+     * Create one or more analytics rules. You can send a single rule object or an array of rule objects.
+     *
+     * @example
+     * $client->analytics->rules()->create(['name' => 'products_query_hits', 'type' => 'popular_queries', 'params' => []])
+     *
+     * @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
+     *
      * @param array $rules Array of rule objects
      * @return array Response from the API
      */
@@ -30,8 +35,13 @@ public function create(array $rules)
     }
 
     /**
-     * Retrieve all analytics rules
-     * 
+     * Retrieve all analytics rules.
+     *
+     * @example
+     * $client->analytics->rules()->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
+     *
      * @return array Response from the API
      */
     public function retrieve()

From a8485d3c2c1917499562ff34a046c51f33860f20 Mon Sep 17 00:00:00 2001
From: Fanis Tharropoulos <ftharropoulos@gmail.com>
Date: Mon, 25 May 2026 14:56:43 +0300
Subject: [PATCH 09/21] docs(analytics-v1): add phpdoc for legacy v1 analytics
 class methods

---
 src/AnalyticsEventsV1.php |  7 +++++++
 src/AnalyticsRuleV1.php   | 16 ++++++++++++++++
 src/AnalyticsRulesV1.php  | 16 ++++++++++++++++
 src/AnalyticsV1.php       | 26 ++++++++++++++++++++++++++
 4 files changed, 65 insertions(+)

diff --git a/src/AnalyticsEventsV1.php b/src/AnalyticsEventsV1.php
index 407e1a6b..61d83c71 100644
--- a/src/AnalyticsEventsV1.php
+++ b/src/AnalyticsEventsV1.php
@@ -27,6 +27,13 @@ public function __construct(ApiCall $apiCall)
     }
 
     /**
+     * Submit a legacy v1 analytics event.
+     *
+     * @example
+     * $client->analyticsV1->events()->create(['type' => 'click', 'name' => 'products_click', 'data' => []])
+     *
+     * @see https://typesense.org/docs/29.0/api/analytics-query-suggestions.html
+     *
      * @param array $params
      *
      * @return array
diff --git a/src/AnalyticsRuleV1.php b/src/AnalyticsRuleV1.php
index f4b52b52..72066519 100644
--- a/src/AnalyticsRuleV1.php
+++ b/src/AnalyticsRuleV1.php
@@ -13,11 +13,27 @@ public function __construct(string $ruleName, ApiCall $apiCall)
         $this->apiCall  = $apiCall;
     }
 
+    /**
+     * Retrieve a legacy v1 analytics rule by name.
+     *
+     * @example
+     * $client->analyticsV1->rules()['rule-1']->retrieve()
+     *
+     * @see https://typesense.org/docs/29.0/api/analytics-query-suggestions.html
+     */
     public function retrieve()
     {
         return $this->apiCall->get($this->endpointPath(), []);
     }
 
+    /**
+     * Delete a legacy v1 analytics rule by name.
+     *
+     * @example
+     * $client->analyticsV1->rules()['rule-1']->delete()
+     *
+     * @see https://typesense.org/docs/29.0/api/analytics-query-suggestions.html
+     */
     public function delete()
     {
         return $this->apiCall->delete($this->endpointPath());
diff --git a/src/AnalyticsRulesV1.php b/src/AnalyticsRulesV1.php
index 59924fc7..b9662cac 100644
--- a/src/AnalyticsRulesV1.php
+++ b/src/AnalyticsRulesV1.php
@@ -22,11 +22,27 @@ public function __get($ruleName)
         return $this->analyticsRules[$ruleName];
     }
 
+    /**
+     * Upsert a legacy v1 analytics rule by name.
+     *
+     * @example
+     * $client->analyticsV1->rules()->upsert('products_query_hits', ['type' => 'popular_queries', 'params' => []])
+     *
+     * @see https://typesense.org/docs/29.0/api/analytics-query-suggestions.html
+     */
     public function upsert($ruleName, $params)
     {
         return $this->apiCall->put($this->endpoint_path($ruleName), $params);
     }
 
+    /**
+     * Retrieve all legacy v1 analytics rules.
+     *
+     * @example
+     * $client->analyticsV1->rules()->retrieve()
+     *
+     * @see https://typesense.org/docs/29.0/api/analytics-query-suggestions.html
+     */
     public function retrieve()
     {
         return $this->apiCall->get($this->endpoint_path(), []);
diff --git a/src/AnalyticsV1.php b/src/AnalyticsV1.php
index 371a1bb0..d04d6e37 100644
--- a/src/AnalyticsV1.php
+++ b/src/AnalyticsV1.php
@@ -2,6 +2,9 @@
 
 namespace Typesense;
 
+/**
+ * @deprecated Deprecated starting with Typesense Server v30. Please migrate to `$client->analytics` (new Analytics APIs).
+ */
 class AnalyticsV1
 {
     const RESOURCE_PATH = '/analytics';
@@ -17,6 +20,19 @@ public function __construct(ApiCall $apiCall)
         $this->apiCall = $apiCall;
     }
 
+    /**
+     * Access the legacy v1 analytics rules resource. Use as a method-style endpoint to list or upsert rules,
+     * or chain `[$id]` on the returned object to access a single rule.
+     *
+     * @example
+     * $client->analyticsV1->rules()->retrieve()
+     * @example
+     * $client->analyticsV1->rules()['rule-1']->retrieve()
+     *
+     * @see https://typesense.org/docs/29.0/api/analytics-query-suggestions.html
+     *
+     * @deprecated Deprecated starting with Typesense Server v30. Please migrate to `$client->analytics` (new Analytics APIs).
+     */
     public function rules()
     {
         if (!isset($this->rules)) {
@@ -25,6 +41,16 @@ public function rules()
         return $this->rules;
     }
 
+    /**
+     * Access the legacy v1 analytics events resource to send analytics events.
+     *
+     * @example
+     * $client->analyticsV1->events()->create(['type' => 'click', 'name' => 'products_click', 'data' => []])
+     *
+     * @see https://typesense.org/docs/29.0/api/analytics-query-suggestions.html
+     *
+     * @deprecated Deprecated starting with Typesense Server v30. Please migrate to `$client->analytics` (new Analytics APIs).
+     */
     public function events()
     {
         if (!isset($this->events)) {

From cafba0368f49fa46d96a0f978201c164e9e6ffb2 Mon Sep 17 00:00:00 2001
From: Fanis Tharropoulos <ftharropoulos@gmail.com>
Date: Mon, 25 May 2026 14:56:57 +0300
Subject: [PATCH 10/21] docs(stemming): add phpdoc for stemming class methods

---
 src/Stemming.php             | 11 +++++++++++
 src/StemmingDictionaries.php | 16 ++++++++++++++++
 src/StemmingDictionary.php   |  8 ++++++++
 3 files changed, 35 insertions(+)

diff --git a/src/Stemming.php b/src/Stemming.php
index 0b72be33..61d3de11 100644
--- a/src/Stemming.php
+++ b/src/Stemming.php
@@ -16,6 +16,17 @@ public function __construct(ApiCall $apiCall)
         $this->apiCall = $apiCall;
     }
 
+    /**
+     * Access the stemming dictionaries resource. Use as a method-style endpoint to list or import
+     * dictionaries, or chain `[$id]` on the returned object to access a single dictionary.
+     *
+     * @example
+     * $client->stemming->dictionaries()->retrieve()
+     * @example
+     * $client->stemming->dictionaries()['en']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/stemming.html
+     */
     public function dictionaries()
     {
         if (!isset($this->typesenseDictionaries)) {
diff --git a/src/StemmingDictionaries.php b/src/StemmingDictionaries.php
index 1a5d66c2..9517c065 100644
--- a/src/StemmingDictionaries.php
+++ b/src/StemmingDictionaries.php
@@ -22,6 +22,14 @@ public function __get($id)
         return $this->typesenseDictionaries[$id];
     }
 
+    /**
+     * Upload a JSONL file containing word mappings to create or update a stemming dictionary.
+     *
+     * @example
+     * $client->stemming->dictionaries()->upsert('irregular-plurals', [['word' => 'people', 'root' => 'person']])
+     *
+     * @see https://typesense.org/docs/latest/api/stemming.html
+     */
     public function upsert($id, $wordRootCombinations)
     {
         $dictionaryInJSONLFormat = is_array($wordRootCombinations) ? implode(
@@ -45,6 +53,14 @@ static function ($item) {
         ) : $resultsInJSONLFormat;
     }
 
+    /**
+     * Retrieve a list of all available stemming dictionaries.
+     *
+     * @example
+     * $client->stemming->dictionaries()->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/stemming.html
+     */
     public function retrieve()
     {
         $response = $this->apiCall->get(StemmingDictionaries::RESOURCE_PATH, []);
diff --git a/src/StemmingDictionary.php b/src/StemmingDictionary.php
index 6fbdb5c1..078d5e3f 100644
--- a/src/StemmingDictionary.php
+++ b/src/StemmingDictionary.php
@@ -13,6 +13,14 @@ public function __construct(string $id, ApiCall $apiCall)
         $this->apiCall  = $apiCall;
     }
 
+    /**
+     * Fetch details of a specific stemming dictionary.
+     *
+     * @example
+     * $client->stemming->dictionaries()['en']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/stemming.html
+     */
     public function retrieve()
     {
         return $this->apiCall->get($this->endpointPath(), []);

From ac29b5c5a18fe97c33db9de1c36a3d99f5f3e60a Mon Sep 17 00:00:00 2001
From: Fanis Tharropoulos <ftharropoulos@gmail.com>
Date: Mon, 25 May 2026 14:56:57 +0300
Subject: [PATCH 11/21] docs(collections): add phpdoc for collection class
 methods

---
 src/Collection.php  | 52 +++++++++++++++++++++++++++++++++++++++++++++
 src/Collections.php | 14 ++++++++++++
 2 files changed, 66 insertions(+)

diff --git a/src/Collection.php b/src/Collection.php
index bc859663..bd3b4101 100644
--- a/src/Collection.php
+++ b/src/Collection.php
@@ -25,16 +25,46 @@ class Collection
     private ApiCall $apiCall;
 
     /**
+     * Access the documents resource for this collection. Use as a method-style endpoint
+     * to index, search, import or export documents, or as an array to access a single document.
+     *
+     * @example
+     * $client->collections['products']->documents->create(['id' => '1', 'title' => 'Hat'])
+     * @example
+     * $client->collections['products']->documents['1']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/documents.html
+     *
      * @var Documents
      */
     public Documents $documents;
 
     /**
+     * Access the legacy overrides (curation rules) for this collection. Use it to upsert
+     * or list overrides, or as an array to access a single override by ID.
+     *
+     * @example
+     * $client->collections['products']->overrides->upsert('promote-hat', ['rule' => ['query' => 'hat', 'match' => 'exact'], 'includes' => []])
+     * @example
+     * $client->collections['products']->overrides['promote-hat']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/curation.html
+     *
      * @var Overrides
      */
     public Overrides $overrides;
 
     /**
+     * Access the legacy synonyms for this collection. Use it to upsert or list synonyms,
+     * or as an array to access a single synonym by ID.
+     *
+     * @example
+     * $client->collections['products']->synonyms->upsert('syn-1', ['synonyms' => ['nyc', 'new york']])
+     * @example
+     * $client->collections['products']->synonyms['syn-1']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/synonyms.html
+     *
      * @var Synonyms
      */
     public Synonyms $synonyms;
@@ -121,6 +151,13 @@ public function exists(): ?bool
     }
 
     /**
+     * Retrieve the details of a collection, given its name.
+     *
+     * @example
+     * $client->collections['products']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/collections.html#retrieve-a-collection
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
@@ -130,6 +167,13 @@ public function retrieve(): array
     }
 
     /**
+     * Update a collection's schema to modify the fields and their types.
+     *
+     * @example
+     * $client->collections['products']->update(['fields' => [['name' => 'tags', 'type' => 'string[]']]])
+     *
+     * @see https://typesense.org/docs/latest/api/collections.html#update-or-alter-a-collection
+     *
      * @param array $schema
      *
      * @return array
@@ -141,6 +185,14 @@ public function update(array $schema): array
     }
 
     /**
+     * Permanently drops a collection. This action cannot be undone. For large collections,
+     * this might have an impact on read latencies.
+     *
+     * @example
+     * $client->collections['products']->delete()
+     *
+     * @see https://typesense.org/docs/latest/api/collections.html#drop-a-collection
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
diff --git a/src/Collections.php b/src/Collections.php
index 6a3942c8..c0659f90 100644
--- a/src/Collections.php
+++ b/src/Collections.php
@@ -54,6 +54,13 @@ public function __get($collectionName)
     }
 
     /**
+     * When a collection is created, we give it a name and describe the fields that will be indexed from the documents added to the collection.
+     *
+     * @example
+     * $client->collections->create(['name' => 'products', 'fields' => [['name' => 'title', 'type' => 'string']]])
+     *
+     * @see https://typesense.org/docs/latest/api/collections.html#create-a-collection
+     *
      * @param array $schema
      * @param array $options
      *
@@ -66,6 +73,13 @@ public function create(array $schema, array $options = []): array
     }
 
     /**
+     * Returns a summary of all your collections. The collections are returned sorted by creation date, with the most recent collections appearing first.
+     *
+     * @example
+     * $client->collections->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/collections.html#list-all-collections
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */

From 7a442ec1e3c9799ca6e426138c8197b7cd185587 Mon Sep 17 00:00:00 2001
From: Fanis Tharropoulos <ftharropoulos@gmail.com>
Date: Mon, 25 May 2026 14:56:57 +0300
Subject: [PATCH 12/21] docs(documents): add phpdoc for document class methods

---
 src/Document.php  | 21 +++++++++++++++++
 src/Documents.php | 57 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 78 insertions(+)

diff --git a/src/Document.php b/src/Document.php
index d47d0c4c..cd4210fc 100644
--- a/src/Document.php
+++ b/src/Document.php
@@ -58,6 +58,13 @@ private function endpointPath(): string
     }
 
     /**
+     * Fetch an individual document from a collection by using its ID.
+     *
+     * @example
+     * $client->collections['products']->documents['1']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/documents.html#retrieve-a-document
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
@@ -67,6 +74,13 @@ public function retrieve(): array
     }
 
     /**
+     * Update an individual document by ID by merging the provided fields.
+     *
+     * @example
+     * $client->collections['products']->documents['1']->update(['in_stock' => true])
+     *
+     * @see https://typesense.org/docs/latest/api/documents.html#update-a-document
+     *
      * @param array $partialDocument
      * @param array $options
      *
@@ -79,6 +93,13 @@ public function update(array $partialDocument, array $options = []): array
     }
 
     /**
+     * Delete an individual document from a collection by using its ID.
+     *
+     * @example
+     * $client->collections['products']->documents['1']->delete()
+     *
+     * @see https://typesense.org/docs/latest/api/documents.html#delete-a-document
+     *
      * @param array $options
      * @return array
      * @throws TypesenseClientError|HttpClientException
diff --git a/src/Documents.php b/src/Documents.php
index 09fc201d..1bb79d55 100644
--- a/src/Documents.php
+++ b/src/Documents.php
@@ -60,6 +60,13 @@ private function endPointPath(string $action = ''): string
     }
 
     /**
+     * Index a single document. The document must conform to the schema of the collection.
+     *
+     * @example
+     * $client->collections['products']->documents->create(['id' => '1', 'title' => 'Hat'])
+     *
+     * @see https://typesense.org/docs/latest/api/documents.html#index-a-single-document
+     *
      * @param array $document
      * @param array $options
      *
@@ -72,6 +79,13 @@ public function create(array $document, array $options = []): array
     }
 
     /**
+     * Upsert a single document. Creates the document if it does not exist, otherwise updates it.
+     *
+     * @example
+     * $client->collections['products']->documents->upsert(['id' => '1', 'title' => 'Hat'])
+     *
+     * @see https://typesense.org/docs/latest/api/documents.html#upsert
+     *
      * @param array $document
      * @param array $options
      *
@@ -89,6 +103,16 @@ public function upsert(array $document, array $options = []): array
     }
 
     /**
+     * Update documents matching a `filter_by` condition, or update a single document with
+     * `action: "update"` semantics.
+     *
+     * @example
+     * $client->collections['products']->documents->update(['in_stock' => true], ['filter_by' => 'category:=hats'])
+     * @example
+     * $client->collections['products']->documents->update(['id' => '1', 'title' => 'Hat'])
+     *
+     * @see https://typesense.org/docs/latest/api/documents.html#update-documents-with-conditional-query
+     *
      * @param array $document
      * @param array $options
      *
@@ -131,6 +155,15 @@ public function createMany(array $documents, array $options = []): array
     }
 
     /**
+     * Import documents into a collection. Accepts a JSONL string or an array of document objects.
+     *
+     * @example
+     * $client->collections['products']->documents->import([['id' => '1', 'title' => 'Hat'], ['id' => '2', 'title' => 'Shirt']])
+     * @example
+     * $client->collections['products']->documents->import($jsonlString)
+     *
+     * @see https://typesense.org/docs/latest/api/documents.html#index-multiple-documents
+     *
      * @param string|array $documents
      * @param array $options
      *
@@ -168,6 +201,13 @@ public function import($documents, array $options = [])
     }
 
     /**
+     * Export all documents in a collection as a JSONL string.
+     *
+     * @example
+     * $client->collections['products']->documents->export()
+     *
+     * @see https://typesense.org/docs/latest/api/documents.html#export-documents
+     *
      * @param array $queryParams
      *
      * @return string
@@ -179,6 +219,16 @@ public function export(array $queryParams = []): string
     }
 
     /**
+     * Delete a bunch of documents that match a specific filter condition,
+     * or truncate the collection.
+     *
+     * @example
+     * $client->collections['products']->documents->delete(['filter_by' => 'in_stock:=false'])
+     * @example
+     * $client->collections['products']->documents->delete(['truncate' => true])
+     *
+     * @see https://typesense.org/docs/latest/api/documents.html#delete-by-query
+     *
      * @param array $queryParams
      *
      * @return array
@@ -190,6 +240,13 @@ public function delete(array $queryParams = []): array
     }
 
     /**
+     * Search for documents in this collection.
+     *
+     * @example
+     * $client->collections['products']->documents->search(['q' => '*'])
+     *
+     * @see https://typesense.org/docs/latest/api/documents.html#search
+     *
      * @param array $searchParams
      *
      * @return array

From 67b1127f5bf104a1d6f6cda126761abcf6fb9e1e Mon Sep 17 00:00:00 2001
From: Fanis Tharropoulos <ftharropoulos@gmail.com>
Date: Mon, 25 May 2026 14:56:57 +0300
Subject: [PATCH 13/21] docs(aliases): add phpdoc for alias class methods

---
 src/Alias.php   | 14 ++++++++++++++
 src/Aliases.php | 14 ++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/src/Alias.php b/src/Alias.php
index 9c1560f6..44f8c6c7 100644
--- a/src/Alias.php
+++ b/src/Alias.php
@@ -45,6 +45,13 @@ public function endPointPath(): string
     }
 
     /**
+     * Find out which collection an alias points to by fetching it.
+     *
+     * @example
+     * $client->aliases['my-alias']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/collection-alias.html#retrieve-an-alias
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
@@ -54,6 +61,13 @@ public function retrieve(): array
     }
 
     /**
+     * Delete an alias.
+     *
+     * @example
+     * $client->aliases['my-alias']->delete()
+     *
+     * @see https://typesense.org/docs/latest/api/collection-alias.html#delete-an-alias
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
diff --git a/src/Aliases.php b/src/Aliases.php
index b4eac737..61da92f6 100644
--- a/src/Aliases.php
+++ b/src/Aliases.php
@@ -47,6 +47,13 @@ public function endPointPath(string $aliasName): string
     }
 
     /**
+     * Create or update an alias mapping for a collection.
+     *
+     * @example
+     * $client->aliases->upsert('my-alias', ['collection_name' => 'products'])
+     *
+     * @see https://typesense.org/docs/latest/api/collection-alias.html#upsert-an-alias
+     *
      * @param string $name
      * @param array $mapping
      *
@@ -59,6 +66,13 @@ public function upsert(string $name, array $mapping): array
     }
 
     /**
+     * List all aliases and the collections they map to.
+     *
+     * @example
+     * $client->aliases->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/collection-alias.html#list-all-aliases
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */

From 02064d8542679b107296059727f2a894d66c5ea4 Mon Sep 17 00:00:00 2001
From: Fanis Tharropoulos <ftharropoulos@gmail.com>
Date: Mon, 25 May 2026 14:56:57 +0300
Subject: [PATCH 14/21] docs(keys): add phpdoc for api key class methods

---
 src/Key.php  | 14 ++++++++++++++
 src/Keys.php | 21 +++++++++++++++++++++
 2 files changed, 35 insertions(+)

diff --git a/src/Key.php b/src/Key.php
index 203cd2f2..80361515 100644
--- a/src/Key.php
+++ b/src/Key.php
@@ -45,6 +45,13 @@ private function endpointPath(): string
     }
 
     /**
+     * Retrieve (metadata about) a key. Only the key prefix is returned when you retrieve a key. Due to security reasons, only the create endpoint returns the full API key.
+     *
+     * @example
+     * $client->keys[1]->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/api-keys.html#retrieve-an-api-key
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
@@ -54,6 +61,13 @@ public function retrieve(): array
     }
 
     /**
+     * Delete an API key given its ID.
+     *
+     * @example
+     * $client->keys[1]->delete()
+     *
+     * @see https://typesense.org/docs/latest/api/api-keys.html#delete-api-key
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
diff --git a/src/Keys.php b/src/Keys.php
index 4327f7dc..66f0b388 100644
--- a/src/Keys.php
+++ b/src/Keys.php
@@ -37,6 +37,13 @@ public function __construct(ApiCall $apiCall)
     }
 
     /**
+     * Create an API Key with fine-grain access control. You can restrict access on both a per-collection and per-action level. The generated key is returned only during creation. You want to store this key carefully in a secure place.
+     *
+     * @example
+     * $client->keys->create(['description' => 'Search-only key', 'actions' => ['documents:search'], 'collections' => ['*']])
+     *
+     * @see https://typesense.org/docs/latest/api/api-keys.html#create-an-api-key
+     *
      * @param array $schema
      *
      * @return array
@@ -48,6 +55,13 @@ public function create(array $schema): array
     }
 
     /**
+     * Generate a scoped search-only API key with embedded parameters such as `filter_by` or `expires_at`.
+     *
+     * @example
+     * $client->keys->generateScopedSearchKey('xyz', ['filter_by' => 'company_id:124'])
+     *
+     * @see https://typesense.org/docs/latest/api/api-keys.html#generate-scoped-search-key
+     *
      * @param string $searchKey
      * @param array $parameters
      *
@@ -78,6 +92,13 @@ public function generateScopedSearchKey(
     }
 
     /**
+     * Retrieve (metadata about) all keys.
+     *
+     * @example
+     * $client->keys->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/api-keys.html#list-all-keys
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */

From bc1b2a95d3498afcd966199b8f33820fb89e13d7 Mon Sep 17 00:00:00 2001
From: Fanis Tharropoulos <ftharropoulos@gmail.com>
Date: Mon, 25 May 2026 14:57:05 +0300
Subject: [PATCH 15/21] docs(presets): add phpdoc for preset class methods

---
 src/Preset.php  | 14 ++++++++++++++
 src/Presets.php | 23 ++++++++++++++++++++++-
 2 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/src/Preset.php b/src/Preset.php
index 7c74214a..3c9b1aa0 100644
--- a/src/Preset.php
+++ b/src/Preset.php
@@ -35,6 +35,13 @@ public function __construct(string $presetName, ApiCall $apiCall)
     }
 
     /**
+     * Retrieve the details of a preset, given its name.
+     *
+     * @example
+     * $client->presets['listing_view']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/search.html#presets
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
@@ -44,6 +51,13 @@ public function retrieve(): array
     }
 
     /**
+     * Permanently deletes a preset, given its name.
+     *
+     * @example
+     * $client->presets['listing_view']->delete()
+     *
+     * @see https://typesense.org/docs/latest/api/search.html#presets
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
diff --git a/src/Presets.php b/src/Presets.php
index d18044cf..72c0597d 100644
--- a/src/Presets.php
+++ b/src/Presets.php
@@ -39,6 +39,13 @@ public function __construct(ApiCall $apiCall)
     }
 
     /**
+     * Run a multi-search request using a previously saved preset.
+     *
+     * @example
+     * $client->presets->searchWithPreset('listing_view')
+     *
+     * @see https://typesense.org/docs/latest/api/search.html#presets
+     *
      * @param $presetName
      * @return array|string
      * @throws HttpClientException
@@ -50,6 +57,13 @@ public function searchWithPreset($presetName)
     }
 
     /**
+     * Retrieve the details of all presets.
+     *
+     * @example
+     * $client->presets->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/search.html#presets
+     *
      * @return array|string
      * @throws HttpClientException
      * @throws TypesenseClientError
@@ -60,8 +74,15 @@ public function retrieve()
     }
 
     /**
+     * Create or update an existing preset.
+     *
+     * @example
+     * $client->presets->upsert('listing_view', ['value' => ['q' => '*']])
+     *
+     * @see https://typesense.org/docs/latest/api/search.html#presets
+     *
      * @param string $presetName
-     * @param array $options
+     * @param array $presetsData
      *
      * @return array
      * @throws HttpClientException

From 1ada2523f1fc9113b9734a960f003e3de8e595b7 Mon Sep 17 00:00:00 2001
From: Fanis Tharropoulos <ftharropoulos@gmail.com>
Date: Mon, 25 May 2026 14:57:05 +0300
Subject: [PATCH 16/21] docs(stopwords): add phpdoc for stopword class methods

---
 src/Stopwords.php | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/src/Stopwords.php b/src/Stopwords.php
index 3afe0b7a..240a655b 100644
--- a/src/Stopwords.php
+++ b/src/Stopwords.php
@@ -32,6 +32,13 @@ public function __construct(ApiCall $apiCall)
     }
 
     /**
+     * Retrieve the details of a stopwords set, given its name.
+     *
+     * @example
+     * $client->stopwords->get('en')
+     *
+     * @see https://typesense.org/docs/latest/api/stopwords.html
+     *
      * @return array|string
      * @throws HttpClientException
      * @throws TypesenseClientError
@@ -45,6 +52,13 @@ public function get(string $stopwordsName)
     }
 
     /**
+     * Retrieve the details of all stopwords sets.
+     *
+     * @example
+     * $client->stopwords->getAll()
+     *
+     * @see https://typesense.org/docs/latest/api/stopwords.html
+     *
      * @return array|string
      * @throws HttpClientException
      * @throws TypesenseClientError
@@ -55,6 +69,13 @@ public function getAll()
     }
 
     /**
+     * Upsert a stopwords set. The set's name must be provided as the `name` key on the array.
+     *
+     * @example
+     * $client->stopwords->put(['name' => 'en', 'stopwords' => ['a', 'the']])
+     *
+     * @see https://typesense.org/docs/latest/api/stopwords.html
+     *
      * @param array $stopwordSet
      *
      * @return array
@@ -67,6 +88,13 @@ public function put(array $stopwordSet)
     }
 
     /**
+     * Permanently deletes a stopwords set, given its name.
+     *
+     * @example
+     * $client->stopwords->delete('en')
+     *
+     * @see https://typesense.org/docs/latest/api/stopwords.html
+     *
      * @param $stopwordsName
      * @return array
      * @throws HttpClientException

From c286c59e0c9522dde9294a943f3d4f32542afa29 Mon Sep 17 00:00:00 2001
From: Fanis Tharropoulos <ftharropoulos@gmail.com>
Date: Mon, 25 May 2026 14:57:06 +0300
Subject: [PATCH 17/21] docs(conversations): add phpdoc for conversation class
 methods

---
 src/Conversation.php       | 21 +++++++++++++++++++++
 src/ConversationModel.php  | 21 +++++++++++++++++++++
 src/ConversationModels.php | 14 ++++++++++++++
 src/Conversations.php      | 10 ++++++++++
 4 files changed, 66 insertions(+)

diff --git a/src/Conversation.php b/src/Conversation.php
index fa384c48..5c18604f 100644
--- a/src/Conversation.php
+++ b/src/Conversation.php
@@ -35,6 +35,13 @@ public function __construct(string $id, ApiCall $apiCall)
     }
 
     /**
+     * Update a conversation's TTL.
+     *
+     * @example
+     * $client->conversations['conv-1']->update(['ttl' => 3600])
+     *
+     * @see https://typesense.org/docs/latest/api/conversational-search-rag.html
+     *
      * @param array $params
      *
      * @return array
@@ -46,6 +53,13 @@ public function update(array $params): array
     }
 
     /**
+     * Retrieve a conversation by ID.
+     *
+     * @example
+     * $client->conversations['conv-1']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/conversational-search-rag.html
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
@@ -55,6 +69,13 @@ public function retrieve(): array
     }
 
     /**
+     * Delete a conversation by ID.
+     *
+     * @example
+     * $client->conversations['conv-1']->delete()
+     *
+     * @see https://typesense.org/docs/latest/api/conversational-search-rag.html
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
diff --git a/src/ConversationModel.php b/src/ConversationModel.php
index 69ec03ee..89ac3ec9 100644
--- a/src/ConversationModel.php
+++ b/src/ConversationModel.php
@@ -35,6 +35,13 @@ public function __construct(string $id, ApiCall $apiCall)
     }
 
     /**
+     * Update a conversation model.
+     *
+     * @example
+     * $client->conversations->typesenseModels['model-1']->update(['model_name' => 'openai/gpt-4', 'max_bytes' => 16384])
+     *
+     * @see https://typesense.org/docs/latest/api/conversational-search-rag.html
+     *
      * @param array $params
      *
      * @return array
@@ -46,6 +53,13 @@ public function update(array $params): array
     }
 
     /**
+     * Retrieve a conversation model.
+     *
+     * @example
+     * $client->conversations->typesenseModels['model-1']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/conversational-search-rag.html
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
@@ -55,6 +69,13 @@ public function retrieve(): array
     }
 
     /**
+     * Delete a conversation model.
+     *
+     * @example
+     * $client->conversations->typesenseModels['model-1']->delete()
+     *
+     * @see https://typesense.org/docs/latest/api/conversational-search-rag.html
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
diff --git a/src/ConversationModels.php b/src/ConversationModels.php
index 19890245..e69224e1 100644
--- a/src/ConversationModels.php
+++ b/src/ConversationModels.php
@@ -52,6 +52,13 @@ public function __get($id)
     }
 
     /**
+     * Create a Conversation Model.
+     *
+     * @example
+     * $client->conversations->typesenseModels->create(['model_name' => 'openai/gpt-4', 'api_key' => '...'])
+     *
+     * @see https://typesense.org/docs/latest/api/conversational-search-rag.html
+     *
      * @param array $params
      *
      * @return array
@@ -63,6 +70,13 @@ public function create(array $params): array
     }
 
     /**
+     * Retrieve all conversation models.
+     *
+     * @example
+     * $client->conversations->typesenseModels->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/conversational-search-rag.html
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
diff --git a/src/Conversations.php b/src/Conversations.php
index c0ccfe92..37842839 100644
--- a/src/Conversations.php
+++ b/src/Conversations.php
@@ -12,6 +12,16 @@ class Conversations implements \ArrayAccess
     public const RESOURCE_PATH = '/conversations';
 
     /**
+     * Access the conversation models resource. Use it to create or list models, or as an array
+     * to access a single model by ID.
+     *
+     * @example
+     * $client->conversations->typesenseModels->create(['model_name' => 'openai/gpt-4', 'api_key' => '...'])
+     * @example
+     * $client->conversations->typesenseModels['model-1']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/conversational-search-rag.html
+     *
      * @var ConversationModels
      */
     public ConversationModels $typesenseModels;

From 3531dbeddf99a20b7daa45fdef3e5da47d9abd9d Mon Sep 17 00:00:00 2001
From: Fanis Tharropoulos <ftharropoulos@gmail.com>
Date: Mon, 25 May 2026 14:57:06 +0300
Subject: [PATCH 18/21] docs(nl-search-models): add phpdoc for nl search model
 class methods

---
 src/NLSearchModel.php  | 21 +++++++++++++++++++++
 src/NLSearchModels.php | 14 ++++++++++++++
 2 files changed, 35 insertions(+)

diff --git a/src/NLSearchModel.php b/src/NLSearchModel.php
index b6750965..8f37a8b6 100644
--- a/src/NLSearchModel.php
+++ b/src/NLSearchModel.php
@@ -35,6 +35,13 @@ public function __construct(string $id, ApiCall $apiCall)
     }
 
     /**
+     * Update an existing NL search model.
+     *
+     * @example
+     * $client->nlSearchModels['model-1']->update(['model_name' => 'openai/gpt-4'])
+     *
+     * @see https://typesense.org/docs/latest/api/natural-language-search.html
+     *
      * @param array $params
      *
      * @return array
@@ -46,6 +53,13 @@ public function update(array $params): array
     }
 
     /**
+     * Retrieve a specific NL search model by its ID.
+     *
+     * @example
+     * $client->nlSearchModels['model-1']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/natural-language-search.html
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
@@ -55,6 +69,13 @@ public function retrieve(): array
     }
 
     /**
+     * Delete a specific NL search model by its ID.
+     *
+     * @example
+     * $client->nlSearchModels['model-1']->delete()
+     *
+     * @see https://typesense.org/docs/latest/api/natural-language-search.html
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
diff --git a/src/NLSearchModels.php b/src/NLSearchModels.php
index dad5b063..9d9a4085 100644
--- a/src/NLSearchModels.php
+++ b/src/NLSearchModels.php
@@ -52,6 +52,13 @@ public function __get($id)
     }
 
     /**
+     * Create a new NL search model.
+     *
+     * @example
+     * $client->nlSearchModels->create(['model_name' => 'openai/gpt-4', 'api_key' => '...'])
+     *
+     * @see https://typesense.org/docs/latest/api/natural-language-search.html
+     *
      * @param array $params
      *
      * @return array
@@ -63,6 +70,13 @@ public function create(array $params): array
     }
 
     /**
+     * Retrieve all NL search models.
+     *
+     * @example
+     * $client->nlSearchModels->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/natural-language-search.html
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */

From 4a09319b046dee89366eb222d64a1ab799853d92 Mon Sep 17 00:00:00 2001
From: Fanis Tharropoulos <ftharropoulos@gmail.com>
Date: Mon, 25 May 2026 14:57:13 +0300
Subject: [PATCH 19/21] docs(synonym-sets): add phpdoc for synonym set class
 methods

---
 src/SynonymSet.php      | 31 +++++++++++++++++++++++++++++++
 src/SynonymSetItem.php  | 21 +++++++++++++++++++++
 src/SynonymSetItems.php |  7 +++++++
 src/SynonymSets.php     | 14 ++++++++++++++
 4 files changed, 73 insertions(+)

diff --git a/src/SynonymSet.php b/src/SynonymSet.php
index e8d5c86a..4b6dc049 100644
--- a/src/SynonymSet.php
+++ b/src/SynonymSet.php
@@ -67,6 +67,13 @@ private function endPointPath(): string
     }
 
     /**
+     * Create or update a synonym set with the given name.
+     *
+     * @example
+     * $client->synonymSets['my-set']->upsert(['items' => [['id' => 'syn-1', 'synonyms' => ['nyc', 'new york']]]])
+     *
+     * @see https://typesense.org/docs/latest/api/synonyms.html
+     *
      * @param array $params
      *
      * @return array
@@ -78,6 +85,13 @@ public function upsert(array $params): array
     }
 
     /**
+     * Retrieve a specific synonym set by its name.
+     *
+     * @example
+     * $client->synonymSets['my-set']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/synonyms.html
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
@@ -87,6 +101,13 @@ public function retrieve(): array
     }
 
     /**
+     * Delete a specific synonym set by its name.
+     *
+     * @example
+     * $client->synonymSets['my-set']->delete()
+     *
+     * @see https://typesense.org/docs/latest/api/synonyms.html
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
@@ -96,6 +117,16 @@ public function delete(): array
     }
 
     /**
+     * Access the items in this synonym set. Use the returned object as an array to access
+     * a single item by ID, or call `retrieve()` to list all items.
+     *
+     * @example
+     * $client->synonymSets['my-set']->getItems()->retrieve()
+     * @example
+     * $client->synonymSets['my-set']->getItems()['syn-1']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/synonyms.html
+     *
      * @return SynonymSetItems
      */
     public function getItems(): SynonymSetItems
diff --git a/src/SynonymSetItem.php b/src/SynonymSetItem.php
index e3ac6971..711b0335 100644
--- a/src/SynonymSetItem.php
+++ b/src/SynonymSetItem.php
@@ -55,6 +55,13 @@ private function endPointPath(): string
     }
 
     /**
+     * Retrieve a specific synonym item by its id.
+     *
+     * @example
+     * $client->synonymSets['my-set']->getItems()['syn-1']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/synonyms.html
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
@@ -64,6 +71,13 @@ public function retrieve(): array
     }
 
     /**
+     * Create or update a synonym set item with the given id.
+     *
+     * @example
+     * $client->synonymSets['my-set']->getItems()['syn-1']->upsert(['synonyms' => ['nyc', 'new york']])
+     *
+     * @see https://typesense.org/docs/latest/api/synonyms.html
+     *
      * @param array $params
      *
      * @return array
@@ -75,6 +89,13 @@ public function upsert(array $params): array
     }
 
     /**
+     * Delete a specific synonym item by its id.
+     *
+     * @example
+     * $client->synonymSets['my-set']->getItems()['syn-1']->delete()
+     *
+     * @see https://typesense.org/docs/latest/api/synonyms.html
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
diff --git a/src/SynonymSetItems.php b/src/SynonymSetItems.php
index ce7141ad..67ab4312 100644
--- a/src/SynonymSetItems.php
+++ b/src/SynonymSetItems.php
@@ -52,6 +52,13 @@ private function endPointPath(): string
     }
 
     /**
+     * Retrieve all synonym items in a set.
+     *
+     * @example
+     * $client->synonymSets['my-set']->getItems()->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/synonyms.html
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
diff --git a/src/SynonymSets.php b/src/SynonymSets.php
index e99f1200..e697157c 100644
--- a/src/SynonymSets.php
+++ b/src/SynonymSets.php
@@ -35,6 +35,13 @@ public function __construct(ApiCall $apiCall)
     }
 
     /**
+     * Create or update a synonym set with the given name.
+     *
+     * @example
+     * $client->synonymSets->upsert('my-set', ['items' => [['id' => 'syn-1', 'synonyms' => ['nyc', 'new york']]]])
+     *
+     * @see https://typesense.org/docs/latest/api/synonyms.html
+     *
      * @param string $synonymSetName
      * @param array $config
      *
@@ -47,6 +54,13 @@ public function upsert(string $synonymSetName, array $config): array
     }
 
     /**
+     * Retrieve all synonym sets.
+     *
+     * @example
+     * $client->synonymSets->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/synonyms.html
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */

From f6396ab499a391953bafb794ff7ccd72c245992a Mon Sep 17 00:00:00 2001
From: Fanis Tharropoulos <ftharropoulos@gmail.com>
Date: Mon, 25 May 2026 14:57:13 +0300
Subject: [PATCH 20/21] docs(curation-sets): add phpdoc for curation set class
 methods

---
 src/CurationSet.php      | 31 +++++++++++++++++++++++++++++++
 src/CurationSetItem.php  | 21 +++++++++++++++++++++
 src/CurationSetItems.php |  7 +++++++
 src/CurationSets.php     | 14 ++++++++++++++
 4 files changed, 73 insertions(+)

diff --git a/src/CurationSet.php b/src/CurationSet.php
index ad466c8e..82867dfd 100644
--- a/src/CurationSet.php
+++ b/src/CurationSet.php
@@ -67,6 +67,13 @@ private function endPointPath(): string
     }
 
     /**
+     * Create or update a curation set with the given name.
+     *
+     * @example
+     * $client->curationSets['my-set']->upsert(['items' => [['id' => 'promote-hat', 'rule' => ['query' => 'hat', 'match' => 'exact']]]])
+     *
+     * @see https://typesense.org/docs/latest/api/curation.html
+     *
      * @param array $params
      *
      * @return array
@@ -78,6 +85,13 @@ public function upsert(array $params): array
     }
 
     /**
+     * Retrieve a specific curation set by its name.
+     *
+     * @example
+     * $client->curationSets['my-set']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/curation.html
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
@@ -87,6 +101,13 @@ public function retrieve(): array
     }
 
     /**
+     * Delete a specific curation set by its name.
+     *
+     * @example
+     * $client->curationSets['my-set']->delete()
+     *
+     * @see https://typesense.org/docs/latest/api/curation.html
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
@@ -96,6 +117,16 @@ public function delete(): array
     }
 
     /**
+     * Access the items in this curation set. Use the returned object as an array to access
+     * a single item by ID, or call `retrieve()` to list all items.
+     *
+     * @example
+     * $client->curationSets['my-set']->getItems()->retrieve()
+     * @example
+     * $client->curationSets['my-set']->getItems()['promote-hat']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/curation.html
+     *
      * @return CurationSetItems
      */
     public function getItems(): CurationSetItems
diff --git a/src/CurationSetItem.php b/src/CurationSetItem.php
index 1f419af0..99440c7d 100644
--- a/src/CurationSetItem.php
+++ b/src/CurationSetItem.php
@@ -55,6 +55,13 @@ private function endPointPath(): string
     }
 
     /**
+     * Retrieve a specific curation item by its id.
+     *
+     * @example
+     * $client->curationSets['my-set']->getItems()['promote-hat']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/curation.html
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
@@ -64,6 +71,13 @@ public function retrieve(): array
     }
 
     /**
+     * Create or update a curation set item with the given id.
+     *
+     * @example
+     * $client->curationSets['my-set']->getItems()['promote-hat']->upsert(['rule' => ['query' => 'hat', 'match' => 'exact'], 'includes' => []])
+     *
+     * @see https://typesense.org/docs/latest/api/curation.html
+     *
      * @param array $params
      *
      * @return array
@@ -75,6 +89,13 @@ public function upsert(array $params): array
     }
 
     /**
+     * Delete a specific curation item by its id.
+     *
+     * @example
+     * $client->curationSets['my-set']->getItems()['promote-hat']->delete()
+     *
+     * @see https://typesense.org/docs/latest/api/curation.html
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
diff --git a/src/CurationSetItems.php b/src/CurationSetItems.php
index 2523fcb6..ef8b207e 100644
--- a/src/CurationSetItems.php
+++ b/src/CurationSetItems.php
@@ -52,6 +52,13 @@ private function endPointPath(): string
     }
 
     /**
+     * Retrieve all curation items in a set.
+     *
+     * @example
+     * $client->curationSets['my-set']->getItems()->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/curation.html
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
diff --git a/src/CurationSets.php b/src/CurationSets.php
index 1dcb079e..08bb9ef8 100644
--- a/src/CurationSets.php
+++ b/src/CurationSets.php
@@ -35,6 +35,13 @@ public function __construct(ApiCall $apiCall)
     }
 
     /**
+     * Create or update a curation set with the given name.
+     *
+     * @example
+     * $client->curationSets->upsert('my-set', ['items' => [['id' => 'promote-hat', 'rule' => ['query' => 'hat', 'match' => 'exact']]]])
+     *
+     * @see https://typesense.org/docs/latest/api/curation.html
+     *
      * @param string $curationSetName
      * @param array $config
      *
@@ -47,6 +54,13 @@ public function upsert(string $curationSetName, array $config): array
     }
 
     /**
+     * Retrieve all curation sets.
+     *
+     * @example
+     * $client->curationSets->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/curation.html
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */

From 46478cb71eca10a09b4755157a5301a4a093f74d Mon Sep 17 00:00:00 2001
From: Fanis Tharropoulos <ftharropoulos@gmail.com>
Date: Mon, 25 May 2026 14:57:13 +0300
Subject: [PATCH 21/21] docs(overrides-synonyms): add phpdoc for legacy
 collection-scoped override and synonym methods

---
 src/Override.php  | 14 ++++++++++++++
 src/Overrides.php | 14 ++++++++++++++
 src/Synonym.php   | 20 ++++++++++++++++++++
 src/Synonyms.php  | 20 ++++++++++++++++++++
 4 files changed, 68 insertions(+)

diff --git a/src/Override.php b/src/Override.php
index cf75f28e..95b88d85 100644
--- a/src/Override.php
+++ b/src/Override.php
@@ -58,6 +58,13 @@ private function endPointPath(): string
     }
 
     /**
+     * Retrieve an override (curation rule) by ID on this collection.
+     *
+     * @example
+     * $client->collections['products']->overrides['promote-hat']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/curation.html
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
@@ -67,6 +74,13 @@ public function retrieve(): array
     }
 
     /**
+     * Delete an override (curation rule) by ID on this collection.
+     *
+     * @example
+     * $client->collections['products']->overrides['promote-hat']->delete()
+     *
+     * @see https://typesense.org/docs/latest/api/curation.html
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
diff --git a/src/Overrides.php b/src/Overrides.php
index 6c15daec..101949f3 100644
--- a/src/Overrides.php
+++ b/src/Overrides.php
@@ -60,6 +60,13 @@ public function endPointPath(string $overrideId = ''): string
     }
 
     /**
+     * Create or update an override (curation rule) on this collection.
+     *
+     * @example
+     * $client->collections['products']->overrides->upsert('promote-hat', ['rule' => ['query' => 'hat', 'match' => 'exact'], 'includes' => []])
+     *
+     * @see https://typesense.org/docs/latest/api/curation.html
+     *
      * @param string $overrideId
      * @param array $config
      *
@@ -72,6 +79,13 @@ public function upsert(string $overrideId, array $config): array
     }
 
     /**
+     * Retrieve all overrides (curation rules) on this collection.
+     *
+     * @example
+     * $client->collections['products']->overrides->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/curation.html
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
diff --git a/src/Synonym.php b/src/Synonym.php
index 3b11fa4e..3754433c 100644
--- a/src/Synonym.php
+++ b/src/Synonym.php
@@ -9,6 +9,8 @@
  * Class synonym
  *
  * @package \Typesense
+ *
+ * @deprecated Deprecated starting with Typesense Server v30. Please migrate to `$client->synonymSets` (new Synonym Sets APIs).
  */
 class Synonym
 {
@@ -56,6 +58,15 @@ private function endPointPath(): string
     }
 
     /**
+     * Retrieve a synonym (legacy v1) by ID on this collection.
+     *
+     * @example
+     * $client->collections['products']->synonyms['syn-1']->retrieve()
+     *
+     * @see https://typesense.org/docs/29.0/api/synonyms.html
+     *
+     * @deprecated Deprecated starting with Typesense Server v30. Please migrate to `$client->synonymSets` (new Synonym Sets APIs).
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
@@ -65,6 +76,15 @@ public function retrieve(): array
     }
 
     /**
+     * Delete a synonym (legacy v1) by ID on this collection.
+     *
+     * @example
+     * $client->collections['products']->synonyms['syn-1']->delete()
+     *
+     * @see https://typesense.org/docs/29.0/api/synonyms.html
+     *
+     * @deprecated Deprecated starting with Typesense Server v30. Please migrate to `$client->synonymSets` (new Synonym Sets APIs).
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
diff --git a/src/Synonyms.php b/src/Synonyms.php
index a4c00364..57a35da1 100644
--- a/src/Synonyms.php
+++ b/src/Synonyms.php
@@ -9,6 +9,8 @@
  * Class Synonyms
  *
  * @package \Typesense
+ *
+ * @deprecated Deprecated starting with Typesense Server v30. Please migrate to `$client->synonymSets` (new Synonym Sets APIs).
  */
 class Synonyms implements \ArrayAccess
 {
@@ -58,6 +60,15 @@ public function endPointPath(string $synonymId = ''): string
     }
 
     /**
+     * Create or update a synonym (legacy v1) on this collection.
+     *
+     * @example
+     * $client->collections['products']->synonyms->upsert('syn-1', ['synonyms' => ['nyc', 'new york']])
+     *
+     * @see https://typesense.org/docs/29.0/api/synonyms.html
+     *
+     * @deprecated Deprecated starting with Typesense Server v30. Please migrate to `$client->synonymSets` (new Synonym Sets APIs).
+     *
      * @param string $synonymId
      * @param array $config
      *
@@ -70,6 +81,15 @@ public function upsert(string $synonymId, array $config): array
     }
 
     /**
+     * Retrieve all synonyms (legacy v1) on this collection.
+     *
+     * @example
+     * $client->collections['products']->synonyms->retrieve()
+     *
+     * @see https://typesense.org/docs/29.0/api/synonyms.html
+     *
+     * @deprecated Deprecated starting with Typesense Server v30. Please migrate to `$client->synonymSets` (new Synonym Sets APIs).
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */