Skip to content

Latest commit

 

History

History
69 lines (49 loc) · 2.1 KB

migrating.rst

File metadata and controls

69 lines (49 loc) · 2.1 KB

Migrating to 4.0

This page summarizes migration from the 3.x line to 4.0.

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.