feat: add capability discovery and feature-gated helper APIs

Author: woxxy

CHANGELOG.md

@@ -8,6 +8,7 @@
 * Expanded helper runtime API coverage (`SHOW WARNINGS`, `SHOW STATUS`, `SHOW INDEX STATUS`, `FLUSH RAMCHUNK`, `FLUSH RTINDEX`, `OPTIMIZE INDEX`, UDF lifecycle checks)
 * Added fluent boolean grouping APIs (`orWhere`, `whereOpen/whereClose`, `orHaving`, `havingOpen/havingClose`) and JOIN builders (`join`, `innerJoin`, `leftJoin`, `rightJoin`, `crossJoin`)
 * Added `orderByKnn()` and broader helper wrappers for operational and Manticore-oriented commands (`SHOW PROFILE/PLAN/THREADS/VERSION/PLUGINS`, table status/settings/indexes, flush/reload/kill, suggest family)
+* Added capability discovery and feature-gating APIs (`Capabilities`, `getCapabilities()`, `supports()`, `requireSupport()`) with `UnsupportedFeatureException` for unsupported command families
 * Added capability-aware runtime tests for optional engine features (`supportsCommand`, Buddy-gated checks)
 * Added and stabilized Sphinx 3 compatibility coverage while preserving Sphinx 2 and Manticore test behavior
 * Migrated CI to GitHub Actions-only validation with strict composer metadata checks

MIGRATING-4.0.md

@@ -43,6 +43,8 @@ Helper methods now validate required identifiers and argument shapes:
 - `setVariable()` validates variable names and array values
 - `callSnippets()` and `callKeywords()` validate required arguments
 - `createFunction()` validates return type (`INT`, `UINT`, `BIGINT`, `FLOAT`, `STRING`)
+- capability-aware APIs are available via `getCapabilities()`/`supports()`
+- feature-gated methods may throw `UnsupportedFeatureException` when unsupported
 
 ### Percolate strict validation
 
@@ -67,3 +69,4 @@ message fragments or exception classes.
 2. Replace implicit coercions with explicit typing/casting in your app layer.
 3. Prefer exception-class checks over exact message equality.
 4. Run your integration tests against your target engine (`Sphinx2`, `Sphinx3`, `Manticore`).
+5. Prefer `supports($feature)` checks before engine-specific helper calls.

README.md

@@ -440,6 +440,18 @@ Remember to `->execute()` to get a result.
 
 	Takes the pairs from a SHOW command and returns an associative array key=>value
 
+* __$helper->getCapabilities()__
+
+	Returns a `Capabilities` object with detected engine/version and feature flags.
+
+* __$helper->supports($feature)__
+
+	Checks whether a named feature is supported by the current backend/runtime.
+
+* __$helper->requireSupport($feature, $context = '')__
+
+	Throws `UnsupportedFeatureException` when the requested feature is not available.
+
 The following methods return a prepared `SphinxQL` object. You can also use `->enqueue($next_object)`:
 
 ```php

docs/helper.rst

@@ -57,9 +57,15 @@ Available Methods
 - ``flushLogs()``
 - ``reloadPlugins()``
 - ``kill($queryId)``
+- ``getCapabilities()``
+- ``supports($feature)``
+- ``requireSupport($feature, $context = '')``
 
 Validation Notes
 ----------------
 
 In 4.0, helper methods validate required identifiers and input shapes and throw
 ``SphinxQLException`` on invalid arguments.
+
+Feature-gated helper methods may throw ``UnsupportedFeatureException`` when the
+current engine/runtime does not support that command family.

docs/query-builder.rst

@@ -83,3 +83,11 @@ JOIN and KNN Ordering
 Vector-oriented ordering is available through:
 
 - ``orderByKnn($field, $k, array $vector, $direction = 'ASC')``
+
+Capability Introspection
+------------------------
+
+``SphinxQL`` exposes runtime capability helpers for connection-aware behavior:
+
+- ``getCapabilities()``
+- ``supports($feature)``

src/Capabilities.php

@@ -0,0 +1,83 @@
+<?php
+
+namespace Foolz\SphinxQL;
+
+/**
+ * Describes detected engine/runtime capabilities.
+ */
+class Capabilities
+{
+    /**
+     * @var string
+     */
+    private $engine;
+
+    /**
+     * @var string
+     */
+    private $version;
+
+    /**
+     * @var array<string,bool>
+     */
+    private $features;
+
+    /**
+     * @param string            $engine
+     * @param string            $version
+     * @param array<string,bool> $features
+     */
+    public function __construct($engine, $version, array $features)
+    {
+        $this->engine = strtoupper((string) $engine);
+        $this->version = (string) $version;
+        $this->features = $features;
+    }
+
+    /**
+     * @return string
+     */
+    public function getEngine()
+    {
+        return $this->engine;
+    }
+
+    /**
+     * @return string
+     */
+    public function getVersion()
+    {
+        return $this->version;
+    }
+
+    /**
+     * @return array<string,bool>
+     */
+    public function getFeatures()
+    {
+        return $this->features;
+    }
+
+    /**
+     * @param string $feature
+     *
+     * @return bool
+     */
+    public function supports($feature)
+    {
+        return !empty($this->features[$feature]);
+    }
+
+    /**
+     * @return array<string,mixed>
+     */
+    public function toArray()
+    {
+        return array(
+            'engine' => $this->engine,
+            'version' => $this->version,
+            'features' => $this->features,
+        );
+    }
+}
+

src/Exception/UnsupportedFeatureException.php

@@ -0,0 +1,9 @@
+<?php
+
+namespace Foolz\SphinxQL\Exception;
+
+class UnsupportedFeatureException extends SphinxQLException
+{
+
+}
+