feat: expand parity matrix and capability ergonomics

Author: woxxy

CHANGELOG.md

@@ -9,6 +9,9 @@
 * 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 `SphinxQL::requireSupport()` passthrough and convenience engine predicates on `Capabilities` (`isManticore`, `isSphinx2`, `isSphinx3`)
+* Added helper parity wrappers for `SHOW CHARACTER SET` and `SHOW COLLATION`
+* Added `docs/feature-matrix.yml` as a feature-level support map across Sphinx2/Sphinx3/Manticore
 * 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

README.md

@@ -90,6 +90,8 @@ We support the following database connection drivers:
 | Sphinx 3.x | Supported | Supported with engine-specific assertions | Full CI lane |
 | Manticore | Supported | Supported + Percolate | Full CI lane |
 
+Detailed feature-level support is tracked in [`docs/feature-matrix.yml`](docs/feature-matrix.yml).
+
 ### Migration to 4.0
 
 See [`MIGRATING-4.0.md`](MIGRATING-4.0.md) for the complete migration checklist,
@@ -452,6 +454,12 @@ Remember to `->execute()` to get a result.
 
 	Throws `UnsupportedFeatureException` when the requested feature is not available.
 
+`SphinxQL` also exposes capability helpers:
+
+* __$sphinxql->getCapabilities()__
+* __$sphinxql->supports($feature)__
+* __$sphinxql->requireSupport($feature, $context = '')__
+
 The following methods return a prepared `SphinxQL` object. You can also use `->enqueue($next_object)`:
 
 ```php
@@ -481,6 +489,8 @@ $result = (new SphinxQL($this->conn))
 * `(new Helper($conn))->showAgentStatus() => 'SHOW AGENT STATUS'`
 * `(new Helper($conn))->showScroll() => 'SHOW SCROLL'`
 * `(new Helper($conn))->showDatabases() => 'SHOW DATABASES'`
+* `(new Helper($conn))->showCharacterSet() => 'SHOW CHARACTER SET'`
+* `(new Helper($conn))->showCollation() => 'SHOW COLLATION'`
 * `(new Helper($conn))->showTables() => 'SHOW TABLES'`
 * `(new Helper($conn))->showVariables() => 'SHOW VARIABLES'`
 * `(new Helper($conn))->showCreateTable($table)`

docs/feature-matrix.yml

@@ -0,0 +1,82 @@
+version: 1
+updated_at: "2026-02-27"
+notes:
+  - "supported means covered by runtime tests in at least one CI lane."
+  - "conditional means feature depends on engine/runtime capability checks."
+
+builder:
+  grouped_where:
+    api: ["where", "orWhere", "whereOpen", "orWhereOpen", "whereClose"]
+    sphinx2: supported
+    sphinx3: supported
+    manticore: supported
+  grouped_having:
+    api: ["having", "orHaving", "havingOpen", "orHavingOpen", "havingClose"]
+    sphinx2: supported
+    sphinx3: supported
+    manticore: supported
+  joins:
+    api: ["join", "innerJoin", "leftJoin", "rightJoin", "crossJoin", "resetJoins"]
+    sphinx2: supported
+    sphinx3: supported
+    manticore: supported
+  order_by_knn_builder:
+    api: ["orderByKnn"]
+    sphinx2: supported
+    sphinx3: supported
+    manticore: supported
+    notes:
+      - "builder-level SQL generation is supported; backend execution support depends on engine/runtime."
+
+helper:
+  core_show:
+    api:
+      - "showMeta"
+      - "showWarnings"
+      - "showStatus"
+      - "showTables"
+      - "showVariables"
+      - "showDatabases"
+      - "showCharacterSet"
+      - "showCollation"
+    sphinx2: supported
+    sphinx3: supported
+    manticore: supported
+  diagnostic_show:
+    api: ["showProfile", "showPlan", "showThreads", "showPlugins", "showQueries"]
+    sphinx2: conditional
+    sphinx3: conditional
+    manticore: conditional
+  table_introspection:
+    api: ["showCreateTable", "showTableStatus", "showTableSettings", "showTableIndexes"]
+    sphinx2: conditional
+    sphinx3: conditional
+    manticore: conditional
+  maintenance:
+    api:
+      - "flushRtIndex"
+      - "truncateRtIndex"
+      - "optimizeIndex"
+      - "showIndexStatus"
+      - "flushRamchunk"
+      - "flushAttributes"
+      - "flushHostnames"
+      - "flushLogs"
+      - "reloadPlugins"
+      - "kill"
+    sphinx2: conditional
+    sphinx3: conditional
+    manticore: conditional
+  suggest_family:
+    api: ["callSuggest", "callQSuggest", "callAutocomplete"]
+    sphinx2: conditional
+    sphinx3: conditional
+    manticore: conditional
+    notes:
+      - "callQSuggest/callAutocomplete are feature-gated and throw UnsupportedFeatureException when unavailable."
+
+capabilities:
+  api: ["Helper.getCapabilities", "Helper.supports", "Helper.requireSupport", "SphinxQL.getCapabilities", "SphinxQL.supports"]
+  sphinx2: supported
+  sphinx3: supported
+  manticore: supported

docs/helper.rst

@@ -30,6 +30,8 @@ Available Methods
 - ``showAgentStatus()``
 - ``showScroll()``
 - ``showDatabases()``
+- ``showCharacterSet()``
+- ``showCollation()``
 - ``showTables($index)``
 - ``showVariables()``
 - ``showCreateTable($table)``

docs/query-builder.rst

@@ -91,3 +91,4 @@ Capability Introspection
 
 - ``getCapabilities()``
 - ``supports($feature)``
+- ``requireSupport($feature, $context = '')``

src/Capabilities.php

@@ -58,6 +58,30 @@ public function getFeatures()
         return $this->features;
     }
 
+    /**
+     * @return bool
+     */
+    public function isManticore()
+    {
+        return $this->engine === 'MANTICORE';
+    }
+
+    /**
+     * @return bool
+     */
+    public function isSphinx2()
+    {
+        return $this->engine === 'SPHINX2';
+    }
+
+    /**
+     * @return bool
+     */
+    public function isSphinx3()
+    {
+        return $this->engine === 'SPHINX3';
+    }
+
     /**
      * @param string $feature
      *
@@ -80,4 +104,3 @@ public function toArray()
         );
     }
 }
-

src/Helper.php

@@ -186,6 +186,26 @@ public function showDatabases()
         return $this->query('SHOW DATABASES');
     }
 
+    /**
+     * Runs query: SHOW CHARACTER SET
+     *
+     * @return SphinxQL
+     */
+    public function showCharacterSet()
+    {
+        return $this->query('SHOW CHARACTER SET');
+    }
+
+    /**
+     * Runs query: SHOW COLLATION
+     *
+     * @return SphinxQL
+     */
+    public function showCollation()
+    {
+        return $this->query('SHOW COLLATION');
+    }
+
     /**
      * Runs query: SHOW TABLES
      *
@@ -275,6 +295,8 @@ public function supports($feature)
             'show_threads',
             'show_plugins',
             'show_queries',
+            'show_character_set',
+            'show_collation',
             'show_table_settings',
             'show_table_indexes',
             'call_suggest',
@@ -297,6 +319,8 @@ public function supports($feature)
                 'show_threads' => 'SHOW THREADS',
                 'show_plugins' => 'SHOW PLUGINS',
                 'show_queries' => 'SHOW QUERIES',
+                'show_character_set' => 'SHOW CHARACTER SET',
+                'show_collation' => 'SHOW COLLATION',
                 'show_table_settings' => 'SHOW TABLE rt SETTINGS',
                 'show_table_indexes' => 'SHOW TABLE rt INDEXES',
                 'call_suggest' => "CALL SUGGEST('teh', 'rt')",

src/SphinxQL.php

@@ -294,6 +294,26 @@ public function supports($feature)
         return (new Helper($this->connection))->supports($feature);
     }
 
+    /**
+     * Throws when a named feature is not supported.
+     *
+     * @param string $feature
+     * @param string $context
+     *
+     * @return self
+     * @throws SphinxQLException
+     */
+    public function requireSupport($feature, $context = '')
+    {
+        if ($this->connection === null) {
+            throw new SphinxQLException('requireSupport() requires an attached connection.');
+        }
+
+        (new Helper($this->connection))->requireSupport($feature, $context);
+
+        return $this;
+    }
+
     /**
      * Avoids having the expressions escaped
      *

tests/SphinxQL/HelperTest.php

@@ -283,6 +283,12 @@ public function testMiscellaneous()
         $query = $this->createHelper()->showDatabases();
         $this->assertEquals('SHOW DATABASES', $query->compile()->getCompiled());
 
+        $query = $this->createHelper()->showCharacterSet();
+        $this->assertEquals('SHOW CHARACTER SET', $query->compile()->getCompiled());
+
+        $query = $this->createHelper()->showCollation();
+        $this->assertEquals('SHOW COLLATION', $query->compile()->getCompiled());
+
         $query = $this->createHelper()->showCreateTable('rt');
         $this->assertEquals('SHOW CREATE TABLE rt', $query->compile()->getCompiled());
 
@@ -432,6 +438,11 @@ public function testCapabilitiesAndSupports()
         $this->assertNotEmpty($caps->getEngine());
         $this->assertTrue($this->createHelper()->supports('grouped_where'));
         $this->assertIsBool($this->createHelper()->supports('show_profile'));
+        $this->assertIsBool($this->createHelper()->supports('show_character_set'));
+        $this->assertIsBool($this->createHelper()->supports('show_collation'));
+        $this->assertSame($caps->isManticore(), $caps->getEngine() === 'MANTICORE');
+        $this->assertSame($caps->isSphinx2(), $caps->getEngine() === 'SPHINX2');
+        $this->assertSame($caps->isSphinx3(), $caps->getEngine() === 'SPHINX3');
     }
 
     public function testSupportsUnknownFeatureValidation()
@@ -473,6 +484,26 @@ public function testShowPluginsExecutionWhenSupported()
         $this->assertIsArray($rows);
     }
 
+    public function testShowCharacterSetExecutionWhenSupported()
+    {
+        if (!TestUtil::supportsCommand($this->conn, 'SHOW CHARACTER SET')) {
+            $this->markTestSkipped('SHOW CHARACTER SET is not supported by this engine.');
+        }
+
+        $rows = $this->createHelper()->showCharacterSet()->execute()->getStored();
+        $this->assertIsArray($rows);
+    }
+
+    public function testShowCollationExecutionWhenSupported()
+    {
+        if (!TestUtil::supportsCommand($this->conn, 'SHOW COLLATION')) {
+            $this->markTestSkipped('SHOW COLLATION is not supported by this engine.');
+        }
+
+        $rows = $this->createHelper()->showCollation()->execute()->getStored();
+        $this->assertIsArray($rows);
+    }
+
     public function testSuggestExecutionWhenSupported()
     {
         if (!TestUtil::supportsCommand($this->conn, "CALL SUGGEST('teh', 'rt')")) {

tests/SphinxQL/SphinxQLTest.php

@@ -1391,6 +1391,19 @@ public function testSphinxQLCapabilitiesAccess()
         $this->assertTrue($query->supports('grouped_where'));
     }
 
+    public function testSphinxQLRequireSupport()
+    {
+        $query = $this->createSphinxQL();
+        if ($query->supports('call_qsuggest')) {
+            $this->assertSame($query, $query->requireSupport('call_qsuggest'));
+
+            return;
+        }
+
+        $this->expectException(Foolz\SphinxQL\Exception\UnsupportedFeatureException::class);
+        $query->requireSupport('call_qsuggest');
+    }
+
     public function testSphinxQLSupportsUnknownFeatureValidation()
     {
         $this->expectException(Foolz\SphinxQL\Exception\SphinxQLException::class);