Baseline Requirements¶

• PHP 8.2+

• mysqli or pdo_mysql extension

Key Behavioral Changes¶

4.0 introduces stricter runtime validation. Invalid query-shape input now throws Foolz\\SphinxQL\\Exception\\SphinxQLException instead of being coerced.

Builder validation highlights:

• unknown setType() values

• compile() without selecting a query type

• invalid from() input

• invalid facet() payload type

• invalid orderBy() / withinGroupOrderBy() direction

• invalid limit() / offset() / groupNBy() values

• invalid IN/NOT IN/BETWEEN value shapes

• missing into($index) for update() before compile/execute

Facet validation highlights:

• empty facet()

• empty function/params in facetFunction() and orderByFunction()

• invalid direction

• invalid limit() / offset() values

Helper validation highlights:

• required identifiers must be non-empty strings

• stricter setVariable() and CALL option validation

• helper feature-gated methods can raise UnsupportedFeatureException

Percolate validation highlights:

• stricter payload checks for documents() and options

• earlier failure for unsupported/invalid document shapes

Exception Message Prefixes¶

Driver exceptions now include explicit source prefixes, for example:

• [mysqli][connect]...

• [mysqli][query]...

• [pdo][connect]...

• [pdo][query]...

Migration Checklist¶

1. Validate user input before passing values to builder/helper methods.

2. Replace implicit coercion assumptions with explicit casting in your app layer.

3. Prefer exception class checks over full-message string equality checks.

4. Run integration tests against your target backend (Sphinx 2, Sphinx 3, or Manticore).

5. Add capability checks (supports()) for backend-specific helper calls.

Repository Source¶

The canonical migration checklist also exists in MIGRATING-4.0.md at repository root.