crazy-goat · s2x · Jul 8, 2026 · Jul 7, 2026 · Jul 8, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -96,6 +96,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **DOC-003: Added `@throws ZVecException` annotations on all FFI-calling methods** (#62)
+  - Added `@throws ZVecException` to ~122 methods across 8 source files (`ZVec`, `ZVecSchema`, `ZVecDoc`, `ZVecIndexParams`, `ZVecVectorQuery`, `ZVecGroupByVectorQuery`, `ZVecFieldSchema`, `ZVecCollectionStats`)
+  - Methods without existing PHPDoc: added single-line `/** @throws ZVecException */` annotation
+  - Methods with existing PHPDoc: added `@throws ZVecException` line inside the existing doc block
+  - Skipped: `__destruct`, `__clone`, `getHandle()`, `ffi()`, `checkStatus()`, and private helper methods
+  - All `php -l` syntax checks pass
+
 - **SMELL-008: Made properties private with getters/setters on reranker data classes** (#89)
   - `ZVecRerankedDoc`: all properties (`$doc`, `$combinedScore`, `$sourceRanks`, `$sourceScores`) are now `private`
   - Added getters: `getDoc()`, `getCombinedScore()`, `getSourceRanks()`, `getSourceScores()`

diff --git a/src/ZVecCollectionStats.php b/src/ZVecCollectionStats.php
@@ -35,16 +35,19 @@ private function __clone()
     {
     }
 
+    /** @throws ZVecException */
     public function getDocCount(): int
     {
         return self::ffi()->zvec_collection_stats_get_doc_count($this->handle);
     }
 
+    /** @throws ZVecException */
     public function getIndexCount(): int
     {
         return self::ffi()->zvec_collection_stats_get_index_count($this->handle);
     }
 
+    /** @throws ZVecException */
     public function getIndexName(int $index): string
     {
         $ptr = self::ffi()->zvec_collection_stats_get_index_name($this->handle, $index);
@@ -54,6 +57,7 @@ public function getIndexName(int $index): string
         return is_string($ptr) ? $ptr : FFI::string($ptr);
     }
 
+    /** @throws ZVecException */
     public function getIndexCompleteness(int $index): float
     {
         return self::ffi()->zvec_collection_stats_get_index_completeness($this->handle, $index);

diff --git a/src/ZVecFieldSchema.php b/src/ZVecFieldSchema.php
@@ -36,67 +36,80 @@ private function __clone()
     {
     }
 
+    /** @throws ZVecException */
     public function getName(): string
     {
         $ptr = self::ffi()->zvec_field_schema_get_name($this->handle);
         return is_string($ptr) ? $ptr : FFI::string($ptr);
     }
 
+    /** @throws ZVecException */
     public function getDataType(): int
     {
         return self::ffi()->zvec_field_schema_get_data_type($this->handle);
     }
 
+    /** @throws ZVecException */
     public function getElementDataType(): int
     {
         return self::ffi()->zvec_field_schema_get_element_data_type($this->handle);
     }
 
+    /** @throws ZVecException */
     public function getElementDataSize(): int
     {
         return self::ffi()->zvec_field_schema_get_element_data_size($this->handle);
     }
 
+    /** @throws ZVecException */
     public function getDimension(): int
     {
         return self::ffi()->zvec_field_schema_get_dimension($this->handle);
     }
 
+    /** @throws ZVecException */
     public function isVectorField(): bool
     {
         return self::ffi()->zvec_field_schema_is_vector_field($this->handle) !== 0;
     }
 
+    /** @throws ZVecException */
     public function isDenseVector(): bool
     {
         return self::ffi()->zvec_field_schema_is_dense_vector($this->handle) !== 0;
     }
 
+    /** @throws ZVecException */
     public function isSparseVector(): bool
     {
         return self::ffi()->zvec_field_schema_is_sparse_vector($this->handle) !== 0;
     }
 
+    /** @throws ZVecException */
     public function isArrayType(): bool
     {
         return self::ffi()->zvec_field_schema_is_array_type($this->handle) !== 0;
     }
 
+    /** @throws ZVecException */
     public function isNullable(): bool
     {
         return self::ffi()->zvec_field_schema_is_nullable($this->handle) !== 0;
     }
 
+    /** @throws ZVecException */
     public function hasInvertIndex(): bool
     {
         return self::ffi()->zvec_field_schema_has_invert_index($this->handle) !== 0;
     }
 
+    /** @throws ZVecException */
     public function hasIndex(): bool
     {
         return self::ffi()->zvec_field_schema_has_index($this->handle) !== 0;
     }
 
+    /** @throws ZVecException */
     public function getIndexType(): int
     {
         return self::ffi()->zvec_field_schema_get_index_type($this->handle);

diff --git a/src/ZVecGroupByVectorQuery.php b/src/ZVecGroupByVectorQuery.php
@@ -44,6 +44,8 @@ class ZVecGroupByVectorQuery implements ZVecQueryInterface
 
     /**
      * @param float[] $vector
+
+     * @throws ZVecException
      */
     public function __construct(string $fieldName, array $vector, string $groupByField, int $groupCount = 2, int $groupTopk = 3)
     {
@@ -101,6 +103,7 @@ public function getHandle(): FFI\CData
         return $this->handle;
     }
 
+    /** @throws ZVecException */
     public function free(): void
     {
         if ($this->closed) {
@@ -113,18 +116,21 @@ public function free(): void
         }
     }
 
+    /** @throws ZVecException */
     public function setGroupByField(string $field): self
     {
         self::ffi()->zvec_group_by_vector_query_set_group_by_field($this->handle, $field);
         return $this;
     }
 
+    /** @throws ZVecException */
     public function setGroupCount(int $count): self
     {
         self::ffi()->zvec_group_by_vector_query_set_group_count($this->handle, $count);
         return $this;
     }
 
+    /** @throws ZVecException */
     public function setGroupTopk(int $topk): self
     {
         self::ffi()->zvec_group_by_vector_query_set_group_topk($this->handle, $topk);
@@ -133,6 +139,8 @@ public function setGroupTopk(int $topk): self
 
     /**
      * GroupByVectorQuery does not support general topk; use setGroupTopk() instead.
+
+     * @throws ZVecException
      */
     public function setTopk(int $topk): self
     {
@@ -141,33 +149,38 @@ public function setTopk(int $topk): self
         );
     }
 
+    /** @throws ZVecException */
     public function setRadius(float $radius): self
     {
         $this->radius = $radius;
         self::ffi()->zvec_group_by_vector_query_set_radius($this->handle, $radius);
         return $this;
     }
 
+    /** @throws ZVecException */
     public function setLinear(bool $linear): self
     {
         $this->isLinear = $linear;
         self::ffi()->zvec_group_by_vector_query_set_is_linear($this->handle, $linear ? 1 : 0);
         return $this;
     }
 
+    /** @throws ZVecException */
     public function setUsingRefiner(bool $refiner): self
     {
         $this->isUsingRefiner = $refiner;
         self::ffi()->zvec_group_by_vector_query_set_using_refiner($this->handle, $refiner ? 1 : 0);
         return $this;
     }
 
+    /** @throws ZVecException */
     public function setIncludeVector(bool $include): self
     {
         self::ffi()->zvec_group_by_vector_query_set_include_vector($this->handle, $include ? 1 : 0);
         return $this;
     }
 
+    /** @throws ZVecException */
     public function setFilter(string $filter): self
     {
         self::ffi()->zvec_group_by_vector_query_set_filter($this->handle, $filter);
@@ -176,6 +189,8 @@ public function setFilter(string $filter): self
 
     /**
      * @param string[] $fields
+
+     * @throws ZVecException
      */
     public function setOutputFields(array $fields): self
     {

diff --git a/src/ZVecVectorQuery.php b/src/ZVecVectorQuery.php
@@ -50,6 +50,7 @@ class ZVecVectorQuery implements ZVecQueryInterface
 
     /**
      * @param float[] $vector Dense vector data
+     * @throws ZVecException
      */
     public function __construct(string $fieldName, array $vector)
     {
@@ -122,6 +123,7 @@ public static function fromId(string $fieldName, string $docId): self
         return $query;
     }
 
+    /** @throws ZVecException */
     public function setHnswParams(int $ef): self
     {
         $this->queryParamType = ZVec::QUERY_PARAM_HNSW;
@@ -130,6 +132,7 @@ public function setHnswParams(int $ef): self
         return $this;
     }
 
+    /** @throws ZVecException */
     public function setHnswRabitqParams(int $ef): self
     {
         $this->queryParamType = ZVec::QUERY_PARAM_HNSW_RABITQ;
@@ -138,6 +141,7 @@ public function setHnswRabitqParams(int $ef): self
         return $this;
     }
 
+    /** @throws ZVecException */
     public function setIvfParams(int $nprobe): self
     {
         $this->queryParamType = ZVec::QUERY_PARAM_IVF;
@@ -146,13 +150,15 @@ public function setIvfParams(int $nprobe): self
         return $this;
     }
 
+    /** @throws ZVecException */
     public function setFlatParams(): self
     {
         $this->queryParamType = ZVec::QUERY_PARAM_FLAT;
         self::ffi()->zvec_vector_query_set_flat_mode($this->handle);
         return $this;
     }
 
+    /** @throws ZVecException */
     public function setVamanaParams(int $efSearch): self
     {
         $this->queryParamType = ZVec::QUERY_PARAM_VAMANA;
@@ -161,41 +167,47 @@ public function setVamanaParams(int $efSearch): self
         return $this;
     }
 
+    /** @throws ZVecException */
     public function setRadius(float $radius): self
     {
         $this->radius = $radius;
         self::ffi()->zvec_vector_query_set_radius($this->handle, $radius);
         return $this;
     }
 
+    /** @throws ZVecException */
     public function setLinear(bool $linear): self
     {
         $this->isLinear = $linear;
         self::ffi()->zvec_vector_query_set_is_linear($this->handle, $linear ? 1 : 0);
         return $this;
     }
 
+    /** @throws ZVecException */
     public function setUsingRefiner(bool $refiner): self
     {
         $this->isUsingRefiner = $refiner;
         self::ffi()->zvec_vector_query_set_using_refiner($this->handle, $refiner ? 1 : 0);
         return $this;
     }
 
+    /** @throws ZVecException */
     public function setTopk(int $topk): self
     {
         $this->topk = $topk;
         self::ffi()->zvec_vector_query_set_topk($this->handle, $topk);
         return $this;
     }
 
+    /** @throws ZVecException */
     public function setIncludeVector(bool $include): self
     {
         $this->includeVector = $include;
         self::ffi()->zvec_vector_query_set_include_vector($this->handle, $include ? 1 : 0);
         return $this;
     }
 
+    /** @throws ZVecException */
     public function setFilter(string $filter): self
     {
         $this->filter = $filter;
@@ -205,6 +217,8 @@ public function setFilter(string $filter): self
 
     /**
      * @param string[] $fields
+
+     * @throws ZVecException
      */
     public function setOutputFields(array $fields): self
     {