yf_search_driver abstract class

    public function add($index, $id, $doc)
    {
        return $this->_not_supported(__FUNCTION__);
    }

    public function bulk($index, $docs)
    {
        return $this->_not_supported(__FUNCTION__);
    }

    public function capabilities()
    {
        return ['highlight' => false, 'suggest' => false, 'facets' => false, 'write' => false, 'ddl' => false, 'json' => false];
    }

    public function connect()
    {
        return $this->_not_supported(__FUNCTION__);
    }

    public function create_index($index, $schema = [])
    {
        return $this->_not_supported(__FUNCTION__);
    }

    public function delete($index, $ids)
    {
        return $this->_not_supported(__FUNCTION__);
    }

    public function drop_index($index)
    {
        return $this->_not_supported(__FUNCTION__);
    }

    public function escape($text)
    {
        return $this->_not_supported(__FUNCTION__);
    }

    public function index_exists($index)
    {
        return $this->_not_supported(__FUNCTION__);
    }

    public function is_ready()
    {
        return false;
    }

    public function raw($query)
    {
        return $this->_not_supported(__FUNCTION__);
    }

    abstract public function search(array $params = [], &$error_message = '');

    public function suggest($text, $params = [])
    {
        return $this->_not_supported(__FUNCTION__);
    }

    public function truncate($index)
    {
        return $this->_not_supported(__FUNCTION__);
    }

    public function update($index, $id, $fields)
    {
        return $this->_not_supported(__FUNCTION__);
    }

    public function __call($name, $args)
    {
        return main()->extend_call($this, $name, $args);
    }

    public function _doc_id($id)
    {
        if (is_int($id)) {
            return $id > 0 ? (string) $id : false;
        }
        return is_string($id) && preg_match('~^[1-9][0-9]*\z~', $id) && (string) (int) $id === $id ? $id : false;
    }

    public function _fail($error, &$error_message = '')
    {
        $error_message = $this->last_error = $this->_name() . ': ' . $error;
        return false;
    }

    public function _highlight_html($text, $markers, $pre, $post)
    {
        $stray = [mb_substr($markers[0], 0, 1), mb_substr($markers[1], 0, 1)];
        $html = '';
        foreach (explode($markers[0], (string) $text) as $i => $chunk) {
            $html .= $i ? $pre : '';
            foreach (explode($markers[1], $chunk) as $j => $piece) {
                $html .= ($j ? $post : '') . _prepare_html(str_replace($stray, '', $piece), 0);
            }
        }
        return $html;
    }

    public function _highlight_markers()
    {
        return ["\x02" . bin2hex(random_bytes(6)) . "\x02", "\x03" . bin2hex(random_bytes(6)) . "\x03"];
    }

    public function _is_valid_name($name, $allow_db = false)
    {
        $re = $allow_db ? '~^[a-z_][a-z0-9_]*(\.[a-z_][a-z0-9_]*)?\z~i' : '~^[a-z_][a-z0-9_]*\z~i';
        return is_string($name) && preg_match($re, $name) === 1;
    }

    public function _name()
    {
        $class = get_class($this);
        $pos = strpos($class, 'search_driver_');
        return $pos === false ? $class : substr($class, $pos + strlen('search_driver_'));
    }

    public function _normalize_filter($cond)
    {
        $is_value = fn ($v) => is_scalar($v) && ! (is_float($v) && ! is_finite($v));
        if (is_scalar($cond)) {
            return $is_value($cond) ? [['=', $cond]] : false;
        }
        if ( ! is_array($cond) || ! $cond) {
            return false;
        }
        if (array_is_list($cond)) {
            $cond = ['in' => $cond];
        }
        $out = [];
        foreach ($cond as $op => $value) {
            $op = strtolower(str_replace(' ', '_', (string) $op));
            $op = $op === '<>' ? '!=' : $op;
            if (in_array($op, ['in', 'not_in'], true)) {
                $value = array_values((array) $value);
                if ( ! $value || count(array_filter($value, $is_value)) !== count($value)) {
                    return false;
                }
            } elseif ( ! in_array($op, ['=', '!=', '<', '<=', '>', '>='], true) || ! $is_value($value)) {
                return false;
            }
            $out[] = [$op, $value];
        }
        return $out;
    }

    public function _normalize_params($params, &$error = '')
    {
        $params = (array) $params;
        $q = $params['q'] ?? '';
        $p = [
            'index' => $params['index'] ?? '',
            'q' => is_scalar($q) ? trim((string) $q) : '',
            'id_field' => $params['id_field'] ?? 'id',
        ];
        if ( ! $this->_is_valid_name($p['index'], true)) {
            $error = 'bad or missing index';
            return false;
        }
        if ( ! $this->_is_valid_name($p['id_field'])) {
            $error = 'bad id_field';
            return false;
        }
        $p['fields'] = [];
        foreach ((array) ($params['fields'] ?? []) as $k => $v) {
            [$name, $weight] = is_int($k) ? [$v, 1] : [$k, $v];
            if ( ! $this->_is_valid_name($name) || ! is_numeric($weight) || ! is_finite((float) $weight)) {
                $error = 'bad field';
                return false;
            }
            $p['fields'][$name] = $weight + 0;
        }
        $p['filters'] = [];
        foreach ((array) ($params['filters'] ?? []) as $name => $cond) {
            $cond = $this->_is_valid_name($name) ? $this->_normalize_filter($cond) : false;
            if ($cond === false) {
                $error = 'bad filter on ' . (is_string($name) && $this->_is_valid_name($name) ? $name : 'a field');
                return false;
            }
            $p['filters'][$name] = $cond;
        }
        $p['sort'] = [];
        foreach ((array) ($params['sort'] ?? []) as $k => $v) {
            [$name, $dir] = is_int($k) ? [$v, 'asc'] : [$k, strtolower((string) $v)];
            if (($name !== '_score' && ! $this->_is_valid_name($name)) || ! in_array($dir, ['asc', 'desc'], true)) {
                $error = 'bad sort';
                return false;
            }
            $p['sort'][$name] = $dir;
        }
        $max = max(1, (int) $this->MAX_LIMIT);
        if (isset($params['per_page']) || isset($params['page'])) {
            $p['limit'] = min($max, max(1, (int) ($params['per_page'] ?? $this->DEF_LIMIT)));
            $p['offset'] = (max(1, (int) ($params['page'] ?? 1)) - 1) * $p['limit'];
        } else {
            $p['limit'] = min($max, max(1, (int) ($params['limit'] ?? $this->DEF_LIMIT)));
            $p['offset'] = max(0, (int) ($params['offset'] ?? 0));
        }
        if ($p['offset'] + $p['limit'] > max(1, (int) $this->MAX_WINDOW)) {
            $error = 'page too deep';
            return false;
        }
        $p['highlight'] = [];
        $hl = $params['highlight'] ?? false;
        if ($hl) {
            $hl = is_array($hl) ? $hl : [];
            $hl_fields = array_values((array) ($hl['fields'] ?? array_keys($p['fields'])));
            foreach ($hl_fields as $name) {
                if ( ! $this->_is_valid_name($name)) {
                    $error = 'bad highlight field';
                    return false;
                }
            }
            $p['highlight'] = ['fields' => $hl_fields, 'pre' => (string) ($hl['pre'] ?? '<b>'), 'post' => (string) ($hl['post'] ?? '</b>')];
        }
        foreach (['facets', 'return'] as $key) {
            $p[$key] = array_values((array) ($params[$key] ?? []));
            foreach ($p[$key] as $name) {
                if ( ! $this->_is_valid_name($name)) {
                    $error = 'bad ' . $key . ' field';
                    return false;
                }
            }
        }
        $p['facet_limit'] = min($max, max(1, (int) ($params['facet_limit'] ?? 20)));
        return $p;
    }

    public function _not_supported($method)
    {
        $this->last_error = $this->_name() . ': ' . $method . '() is not supported';
        return false;
    }

    public function _without_id($fields)
    {
        return array_filter($fields, fn ($name) => strtolower((string) $name) !== 'id', ARRAY_FILTER_USE_KEY);
    }

    public function _words($q)
    {
        $q = (string) $q;
        if ( ! mb_check_encoding($q, 'UTF-8')) {
            // preg_split() fails on invalid UTF-8, and no words would match every document: drop the invalid bytes
            $q = (string) json_decode(json_encode($q, JSON_INVALID_UTF8_IGNORE));
        }
        $out = [];
        foreach (preg_split('~\s+~u', trim($q), -1, PREG_SPLIT_NO_EMPTY) ?: [] as $word) {
            $out[mb_strtolower($word)] ??= $word;
        }
        return array_slice(array_values($out), 0, max(1, (int) $this->MAX_WORDS));
    }