feat: add helper parity APIs and advanced query builder clauses

Author: woxxy

CHANGELOG.md

@@ -6,6 +6,9 @@
 * Hardened runtime validation for `SphinxQL`, `Facet`, `Helper`, and `Percolate` input contracts (fail-fast exceptions for invalid query-shape input)
 * Standardized driver exception message prefixes for better diagnostics (`[mysqli][...]`, `[pdo][...]`)
 * 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-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
 * Updated documentation and added a dedicated `MIGRATING-4.0.md` guide

README.md

@@ -16,11 +16,11 @@ This Query Builder has no dependencies except PHP 8.2 or later, `\MySQLi` extens
 
 ### Missing methods?
 
-SphinxQL evolves very fast.
+SphinxQL and ManticoreQL evolve fast. This library provides fluent builders for
+core query composition and helper wrappers for common operational commands.
 
-Most of the new functions are static one liners like `SHOW PLUGINS`. We'll avoid trying to keep up with these methods, as they are easy to just call directly (`(new SphinxQL($conn))->query($sql)->execute()`). You're free to submit pull requests to support these methods.
-
-If any feature is unreachable through this library, open a new issue or send a pull request.
+If any feature is still unreachable through this library, open an issue or send
+a pull request.
 
 ## Code Quality
 
@@ -240,7 +240,8 @@ Will return an array with an `INT` as first member, the number of rows deleted.
     $sq->where('column', 'BETWEEN', array('value1', 'value2'));
 	```
 
-	_It should be noted that `OR` and parenthesis are not supported and implemented in the SphinxQL dialect yet._
+	You can compose grouped boolean filters with:
+	`orWhere()`, `whereOpen()`, `orWhereOpen()`, and `whereClose()`.
 
 #### MATCH
 
@@ -297,6 +298,18 @@ Will return an array with an `INT` as first member, the number of rows deleted.
 
 	Direction can be omitted with `null`, or be `ASC` or `DESC` case insensitive.
 
+* __$sq->orderByKnn($field, $k, array $vector, $direction = 'ASC')__
+
+	`ORDER BY KNN($field, $k, $vector) [$direction]`
+
+#### JOIN
+
+* __$sq->join($table, $left, $operator, $right, $type = 'INNER')__
+* __$sq->innerJoin($table, $left, $operator, $right)__
+* __$sq->leftJoin($table, $left, $operator, $right)__
+* __$sq->rightJoin($table, $left, $operator, $right)__
+* __$sq->crossJoin($table)__
+
 * __$sq->offset($offset)__
 
 	`LIMIT $offset, 9999999999999`
@@ -448,11 +461,27 @@ $result = (new SphinxQL($this->conn))
 * `(new Helper($conn))->showMeta() => 'SHOW META'`
 * `(new Helper($conn))->showWarnings() => 'SHOW WARNINGS'`
 * `(new Helper($conn))->showStatus() => 'SHOW STATUS'`
+* `(new Helper($conn))->showProfile() => 'SHOW PROFILE'`
+* `(new Helper($conn))->showPlan() => 'SHOW PLAN'`
+* `(new Helper($conn))->showThreads() => 'SHOW THREADS'`
+* `(new Helper($conn))->showVersion() => 'SHOW VERSION'`
+* `(new Helper($conn))->showPlugins() => 'SHOW PLUGINS'`
+* `(new Helper($conn))->showAgentStatus() => 'SHOW AGENT STATUS'`
+* `(new Helper($conn))->showScroll() => 'SHOW SCROLL'`
+* `(new Helper($conn))->showDatabases() => 'SHOW DATABASES'`
 * `(new Helper($conn))->showTables() => 'SHOW TABLES'`
 * `(new Helper($conn))->showVariables() => 'SHOW VARIABLES'`
+* `(new Helper($conn))->showCreateTable($table)`
+* `(new Helper($conn))->showTableStatus($table = null)`
+* `(new Helper($conn))->showTableSettings($table)`
+* `(new Helper($conn))->showTableIndexes($table)`
+* `(new Helper($conn))->showQueries()`
 * `(new Helper($conn))->setVariable($name, $value, $global = false)`
 * `(new Helper($conn))->callSnippets($data, $index, $query, $options = array())`
 * `(new Helper($conn))->callKeywords($text, $index, $hits = null)`
+* `(new Helper($conn))->callSuggest($text, $index, $options = array())`
+* `(new Helper($conn))->callQSuggest($text, $index, $options = array())`
+* `(new Helper($conn))->callAutocomplete($text, $index, $options = array())`
 * `(new Helper($conn))->describe($index)`
 * `(new Helper($conn))->createFunction($udf_name, $returns, $soname)`
 * `(new Helper($conn))->dropFunction($udf_name)`
@@ -461,6 +490,11 @@ $result = (new SphinxQL($this->conn))
 * `(new Helper($conn))->optimizeIndex($index)`
 * `(new Helper($conn))->showIndexStatus($index)`
 * `(new Helper($conn))->flushRamchunk($index)`
+* `(new Helper($conn))->flushAttributes()`
+* `(new Helper($conn))->flushHostnames()`
+* `(new Helper($conn))->flushLogs()`
+* `(new Helper($conn))->reloadPlugins()`
+* `(new Helper($conn))->kill($queryId)`
 
 ### Percolate
  The `Percolate` class provides methods for the "Percolate query" feature of Manticore Search.

docs/helper.rst

@@ -22,11 +22,27 @@ Available Methods
 - ``showMeta()``
 - ``showWarnings()``
 - ``showStatus()``
+- ``showProfile()``
+- ``showPlan()``
+- ``showThreads()``
+- ``showVersion()``
+- ``showPlugins()``
+- ``showAgentStatus()``
+- ``showScroll()``
+- ``showDatabases()``
 - ``showTables($index)``
 - ``showVariables()``
+- ``showCreateTable($table)``
+- ``showTableStatus($table = null)``
+- ``showTableSettings($table)``
+- ``showTableIndexes($table)``
+- ``showQueries()``
 - ``setVariable($name, $value, $global = false)``
 - ``callSnippets($data, $index, $query, array $options = array())``
 - ``callKeywords($text, $index, $hits = null)``
+- ``callSuggest($text, $index, array $options = array())``
+- ``callQSuggest($text, $index, array $options = array())``
+- ``callAutocomplete($text, $index, array $options = array())``
 - ``describe($index)``
 - ``createFunction($udfName, $returns, $soName)``
 - ``dropFunction($udfName)``
@@ -36,6 +52,11 @@ Available Methods
 - ``optimizeIndex($index)``
 - ``showIndexStatus($index)``
 - ``flushRamchunk($index)``
+- ``flushAttributes()``
+- ``flushHostnames()``
+- ``flushLogs()``
+- ``reloadPlugins()``
+- ``kill($queryId)``
 
 Validation Notes
 ----------------

docs/query-builder.rst

@@ -62,3 +62,24 @@ The builder now validates critical query-shape input and throws
 - negative ``limit()`` / ``offset()``
 - invalid shapes for ``IN`` and ``BETWEEN`` filters
 - invalid ``facet()`` object type
+
+Boolean Grouping and OR Filters
+-------------------------------
+
+The builder supports grouped boolean filters for ``WHERE`` and ``HAVING``:
+
+- ``orWhere()``
+- ``whereOpen()`` / ``orWhereOpen()`` / ``whereClose()``
+- ``orHaving()``
+- ``havingOpen()`` / ``orHavingOpen()`` / ``havingClose()``
+
+JOIN and KNN Ordering
+---------------------
+
+``SELECT`` queries support fluent joins:
+
+- ``join()``, ``innerJoin()``, ``leftJoin()``, ``rightJoin()``, ``crossJoin()``
+
+Vector-oriented ordering is available through:
+
+- ``orderByKnn($field, $k, array $vector, $direction = 'ASC')``