feat!: harden 4.0 runtime validation, docs, and CI coverage

Author: woxxy

.github/workflows/ci.yml

@@ -15,7 +15,6 @@ jobs:
     name: PHP ${{ matrix.php }} / ${{ matrix.driver }} / ${{ matrix.search_build }}
     runs-on: ubuntu-22.04
     timeout-minutes: 30
-    continue-on-error: ${{ matrix.search_build == 'SPHINX3' }}
     permissions:
       contents: read
       packages: read
@@ -101,8 +100,11 @@ jobs:
           docker logs searchd || true
           exit 1
 
+      - name: Validate composer metadata
+        run: composer validate --strict --no-check-publish
+
       - name: Install dependencies
-        run: composer update --prefer-dist --no-interaction
+        run: composer install --prefer-dist --no-interaction --no-progress
 
       - name: Prepare autoload
         run: composer dump-autoload

CHANGELOG.md

@@ -3,6 +3,12 @@
 * Updated CI PHP matrix to 8.2 and 8.3
 * Restored runtime-level driver normalization for PDO/MySQLi scalar fetch values
 * Normalized MySQLi driver exception handling for modern PHP `mysqli_sql_exception` behavior
+* 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 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
 
 #### 3.0.2
 * Dropped support for PHP 7.3 and lower

MIGRATING-4.0.md

@@ -0,0 +1,69 @@
+# Migrating to 4.0
+
+This guide covers migration from the 3.x line to the 4.0 line.
+
+## Baseline Requirements
+
+- PHP 8.2+
+- `mysqli` or `pdo_mysql` extension
+
+## Major Behavioral Changes
+
+4.0 introduces strict runtime validation for query builder and helper input.
+Invalid query-shape arguments now fail fast with `Foolz\SphinxQL\Exception\SphinxQLException`.
+
+### SphinxQL builder strict validation
+
+The following now throw on invalid input:
+
+- `setType()` unknown query type
+- `compile()` with no selected query type
+- `from()` with empty or invalid index input
+- `facet()` with non-`Facet` argument
+- `orderBy()` / `withinGroupOrderBy()` invalid direction (must be `ASC` or `DESC`)
+- `limit()` / `offset()` negative or invalid integer values
+- `groupNBy()` non-positive values
+- `where()` / `having()` invalid filter value shape for `IN`/`NOT IN`/`BETWEEN`
+- `into()`, `columns()`, `values()`, `value()`, `set()` invalid/empty input
+- `setQueuePrev()` non-`SphinxQL` argument
+
+### Facet strict validation
+
+- empty `facet()` input
+- empty function/params in `facetFunction()` and `orderByFunction()`
+- invalid direction in `orderBy()` / `orderByFunction()`
+- negative or invalid `limit()` / `offset()`
+
+### Helper strict validation
+
+Helper methods now validate required identifiers and argument shapes:
+
+- `showTables()`, `describe()`, `showIndexStatus()`, `flushRtIndex()`,
+  `truncateRtIndex()`, `optimizeIndex()`, `flushRamchunk()`, etc.
+- `setVariable()` validates variable names and array values
+- `callSnippets()` and `callKeywords()` validate required arguments
+- `createFunction()` validates return type (`INT`, `UINT`, `BIGINT`, `FLOAT`, `STRING`)
+
+### Percolate strict validation
+
+Percolate input now rejects invalid payload types earlier instead of relying on
+implicit coercion, and string sanitization paths are null-safe.
+
+## Exception Message Format
+
+Driver-level connection/query exceptions now include a source prefix:
+
+- `[mysqli][connect]...`
+- `[mysqli][query]...`
+- `[pdo][connect]...`
+- `[pdo][query]...`
+
+If your code matches exact exception strings, update those checks to match
+message fragments or exception classes.
+
+## Migration Tips
+
+1. Validate user input before passing it to query builder methods.
+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`).

README.md

@@ -8,7 +8,9 @@ Query Builder for SphinxQL
 
 ## About
 
-This is a SphinxQL Query Builder used to work with SphinxQL, a SQL dialect used with the Sphinx search engine and it's fork Manticore. It maps most of the functions listed in the [SphinxQL reference](http://sphinxsearch.com/docs/current.html#SphinxQL-reference) and is generally [faster](http://sphinxsearch.com/blog/2010/04/25/sphinxapi-vs-SphinxQL-benchmark/) than the available Sphinx API.
+This is a query builder for SphinxQL/ManticoreQL, the SQL dialect used by
+Sphinx Search and Manticore Search. It maps most common query-builder use cases
+and supports both `mysqli` and `PDO` drivers.
 
 This Query Builder has no dependencies except PHP 8.2 or later, `\MySQLi` extension, `PDO`, and [Sphinx](http://sphinxsearch.com)/[Manticore](https://manticoresearch.com).
 
@@ -24,22 +26,22 @@ If any feature is unreachable through this library, open a new issue or send a p
 
 The majority of the methods in the package have been unit tested.
 
-The only methods that have not been fully tested are the Helpers, which are mostly simple shorthands for SQL strings.
+Helper methods and engine compatibility scenarios are covered by the test suite.
 
 ## How to Contribute
 
 ### Pull Requests
 
 1. Fork the SphinxQL Query Builder repository
 2. Create a new branch for each feature or improvement
-3. Submit a pull request from each branch to the **master** branch
+3. Submit a pull request from each branch to the repository default branch
 
 It is very important to separate new features or improvements into separate feature branches, and to send a pull
 request for each branch. This allows me to review and pull in new features or improvements individually.
 
 ### Style Guide
 
-All pull requests must adhere to the [PSR-2](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md) standard.
+All pull requests should follow PSR-12-compatible formatting.
 
 ### Unit Testing
 
@@ -80,6 +82,19 @@ We support the following database connection drivers:
 * Foolz\SphinxQL\Drivers\Mysqli\Connection
 * Foolz\SphinxQL\Drivers\Pdo\Connection
 
+### Engine Compatibility Matrix
+
+| Engine | Query Builder | Helper APIs | Notes |
+| --- | --- | --- | --- |
+| Sphinx 2.x | Supported | Supported | Full CI lane |
+| Sphinx 3.x | Supported | Supported with engine-specific assertions | Full CI lane |
+| Manticore | Supported | Supported + Percolate | Full CI lane |
+
+### Migration to 4.0
+
+See [`MIGRATING-4.0.md`](MIGRATING-4.0.md) for the complete migration checklist,
+including strict runtime validation behavior introduced in the 4.0 line.
+
 ### Connection
 
 * __$conn = new Connection()__
@@ -118,10 +133,6 @@ There are cases when an input __must__ be escaped in the SQL statement. The foll
 
 	Returns the escaped value. This is processed with the `\MySQLi::real_escape_string()` function.
 
-* __$sq->quoteIdentifier($identifier)__
-
-	Adds backtick quotes to the identifier. For array elements, use `$sq->quoteIdentifierArray($arr)`.
-
 * __$sq->quote($value)__
 
 	Adds quotes to the value and escapes it. For array elements, use `$sq->quoteArr($arr)`.
@@ -136,6 +147,15 @@ There are cases when an input __must__ be escaped in the SQL statement. The foll
 
 	_Refer to `$sq->match()` for more information._
 
+#### Strict Validation in 4.0
+
+4.0 performs fail-fast validation for invalid query-shape input. Examples:
+
+* invalid `setType()` values
+* invalid `ORDER BY` direction values
+* negative `limit()`/`offset()`
+* invalid value shapes for `IN`/`BETWEEN`
+
 #### SELECT
 
 * __$sq = (new SphinxQL($conn))->select($column1, $column2, ...)->from($index1, $index2, ...)__

composer.json

@@ -2,14 +2,15 @@
     "name": "foolz/sphinxql-query-builder",
     "replace": {"foolz/sphinxql": "self.version"},
     "type": "library",
-    "description": "A PHP query builder for SphinxQL. Uses MySQLi to connect to the Sphinx server.",
+    "description": "A PHP query builder for SphinxQL and ManticoreQL with MySQLi and PDO drivers.",
     "keywords": ["database", "sphinxql", "sphinx", "search", "SQL", "query builder"],
-    "homepage": "http://www.foolz.us",
+    "homepage": "https://github.com/FoolCode/SphinxQL-Query-Builder",
     "license": "Apache-2.0",
     "authors": [{"name": "foolz", "email": "support@foolz.us"}],
     "support": {
-        "email": "support@foolz.us",
-        "irc": "irc://irc.irchighway.net/fooldriver"
+        "issues": "https://github.com/FoolCode/SphinxQL-Query-Builder/issues",
+        "source": "https://github.com/FoolCode/SphinxQL-Query-Builder",
+        "docs": "https://github.com/FoolCode/SphinxQL-Query-Builder/tree/master/docs"
     },
     "require": {
         "php": "^8.2"

docs/config.rst

@@ -3,10 +3,10 @@
 Configuration
 =============
 
-Obtaining a Connection
-----------------------
+Creating a Connection
+---------------------
 
-You can obtain a SphinxQL Connection with the `Foolz\\SphinxQL\\Drivers\\Mysqli\\Connection` class.
+Use one of the supported drivers:
 
 .. code-block:: php
 
@@ -15,33 +15,37 @@ You can obtain a SphinxQL Connection with the `Foolz\\SphinxQL\\Drivers\\Mysqli\
     use Foolz\SphinxQL\Drivers\Mysqli\Connection;
 
     $conn = new Connection();
-    $conn->setparams(array('host' => '127.0.0.1', 'port' => 9306));
-
-.. warning::
-
-    The existing PDO driver written is considered experimental as the behaviour changes between certain PHP releases.
+    $conn->setParams(array(
+        'host' => '127.0.0.1',
+        'port' => 9306,
+    ));
 
-Connection Parameters
----------------------
+You can also use the PDO driver:
 
-The connection parameters provide information about the instance you wish to establish a connection with. The parameters required is set with the `setParams($array)` or `setParam($key, $value)` methods.
+.. code-block:: php
 
-    .. describe:: host
+    <?php
 
-        :Type: string
-        :Default: 127.0.0.1
+    use Foolz\SphinxQL\Drivers\Pdo\Connection;
 
-    .. describe:: port
+    $conn = new Connection();
+    $conn->setParams(array(
+        'host' => '127.0.0.1',
+        'port' => 9306,
+    ));
 
-        :Type: int
-        :Default: 9306
+Connection Parameters
+---------------------
 
-    .. describe:: socket
+``setParams()`` and ``setParam()`` accept:
 
-        :Type: string
-        :Default: null
+- ``host`` (string, default ``127.0.0.1``)
+- ``port`` (int, default ``9306``)
+- ``socket`` (string|null, default ``null``)
+- ``options`` (array, driver-specific client options)
 
-    .. describe:: options
+Strict Validation Notes
+-----------------------
 
-        :Type: array
-        :Default: null
+The query builder validates critical inputs at runtime in 4.0.
+Prefer explicit values over implicit coercion.

docs/contribute.rst

@@ -6,14 +6,14 @@ Pull Requests
 
 1. Fork `SphinxQL Query Builder <https://github.com/FoolCode/SphinxQL-Query-Builder>`_
 2. Create a new branch for each feature or improvement
-3. Submit a pull request with your branch against the master branch
+3. Submit a pull request with your branch against the default branch
 
 It is very important that you create a new branch for each feature, improvement, or fix so that may review the changes and merge the pull requests in a timely manner.
 
 Coding Style
 ------------
 
-All pull requests must adhere to the `PSR-2 <https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md>`_ standard.
+All pull requests should follow modern PHP style conventions (PSR-12 compatible formatting).
 
 Testing
 -------