# Class yii\sphinx\MatchExpression

Inheritance | yii\sphinx\MatchExpression » yii\base\BaseObject
Implements | yii\base\Configurable
Available since version | 2.0.6
Source Code | https://github.com/yiisoft/yii2-sphinx/blob/master/MatchExpression.php

MatchExpression represents a MATCH SphinxQL expression.

In conjunction with yii\sphinx\MatchBuilder this class provides ability to build sophisticated MATCH expressions. Instance of this class can be passed to yii\sphinx\Query::match(). For example:

    use yii\sphinx\Query;
    use yii\sphinx\MatchExpression;

    $rows = (new Query())
        ->match(new MatchExpression('@title :title', ['title' => 'Yii']))
        ->all();

You may use match(), andMatch() and orMatch() to combine several conditions. For example:

    use yii\sphinx\Query;
    use yii\sphinx\MatchExpression;

    $rows = (new Query())
        ->match(
            // produces '((@title "Yii") (@author "Paul")) | (@content "Sphinx")' :
            (new MatchExpression())
                ->match(['title' => 'Yii'])
                ->andMatch(['author' => 'Paul'])
                ->orMatch(['content' => 'Sphinx'])
        )
        ->all();

You may as well compose expressions with special operators like 'MAYBE', 'PROXIMITY' etc. For example:

    use yii\sphinx\Query;
    use yii\sphinx\MatchExpression;

    $rows = (new Query())
        ->match(
            // produces '@title "Yii" MAYBE "Sphinx"' :
            (new MatchExpression())->match([
                'maybe',
                'title',
                'Yii',
                'Sphinx',
            ])
        )
        ->all();

    $rows = (new Query())
        ->match(
            // produces '@title "Yii"~10' :
            (new MatchExpression())->match([
                'proximity',
                'title',
                'Yii',
                10,
            ])
        )
        ->all();

Note: parameters passed via params() or generated from array conditions will be automatically escaped using yii\sphinx\Connection::escapeMatchValue().

See also:

- yii\sphinx\MatchBuilder
- https://sphinxsearch.com/docs/current.html#extended-syntax

## Public Properties

Hide inherited properties

Property | Type | Description | Defined By
--- | --- | --- | ---
$match | string|array|yii\db\Expression | MATCH expression. | yii\sphinx\MatchExpression
$params | array | List of match expression parameter values indexed by parameter placeholders. | yii\sphinx\MatchExpression

## Public Methods

Hide inherited methods

Method | Description | Defined By
--- | --- | ---
__call() | Calls the named method which is not a class method. | yii\base\BaseObject
__construct() | Constructor. | yii\sphinx\MatchExpression
__get() | Returns the value of an object property. | yii\base\BaseObject
__isset() | Checks if a property is set, i.e. defined and not null. | yii\base\BaseObject
__set() | Sets value of an object property. | yii\base\BaseObject
__unset() | Sets an object property to null. | yii\base\BaseObject
addParams() | Adds additional parameters to be parsed into the query. | yii\sphinx\MatchExpression
andFilterMatch() | Adds an additional MATCH condition to the existing one but ignores empty operands. | yii\sphinx\MatchExpression
andMatch() | Adds an additional MATCH condition to the existing one. | yii\sphinx\MatchExpression
canGetProperty() | Returns a value indicating whether a property can be read. | yii\base\BaseObject
canSetProperty() | Returns a value indicating whether a property can be set. | yii\base\BaseObject
className() | Returns the fully qualified name of this class. | yii\base\BaseObject
filterMatch() | Sets the MATCH part of the query but ignores empty operands. | yii\sphinx\MatchExpression
hasMethod() | Returns a value indicating whether a method is defined. | yii\base\BaseObject
hasProperty() | Returns a value indicating whether a property is defined. | yii\base\BaseObject
init() | Initializes the object. | yii\base\BaseObject
match() | Sets the MATCH expression. | yii\sphinx\MatchExpression
orFilterMatch() | Adds an additional MATCH condition to the existing one but ignores empty operands. | yii\sphinx\MatchExpression
orMatch() | Adds an additional MATCH condition to the existing one. | yii\sphinx\MatchExpression
params() | Sets the parameters to be parsed into the query. | yii\sphinx\MatchExpression

## Protected Methods

Hide inherited methods

Method | Description | Defined By
--- | --- | ---
filterCondition() | Removes empty operands from the given query condition. | yii\sphinx\MatchExpression
isEmpty() | Returns a value indicating whether the give value is "empty". | yii\sphinx\MatchExpression

## Property Details

Hide inherited properties

$match public property

MATCH expression. For example: `['title' => 'Yii', 'content' => 'Sphinx']`. Note: being specified as a plain string this value will not be quoted or escaped, do not pass possible unsecured values (like the ones obtained from HTTP request) as a direct value.

See also match().

public string|array|yii\db\Expression $match = null
$params public property

List of match expression parameter values indexed by parameter placeholders. For example, `[':name' => 'Dan', ':age' => 31]`. These parameters will be automatically escaped using yii\sphinx\Connection::escapeMatchValue() and inserted into MATCH expression as a quoted strings.

public array $params = []

## Method Details

Hide inherited methods

__call() public method

Defined in: yii\base\BaseObject::__call()

Calls the named method which is not a class method.

Do not call this method directly as it is a PHP magic method that will be implicitly called when an unknown method is being invoked.

public mixed __call ( $name, $params )
$name | string | The method name
$params | array | Method parameters
return | mixed | The method return value
throws | yii\base\UnknownMethodException | when calling unknown method

Source code

                    public function __call($name, $params)
    {
        throw new UnknownMethodException('Calling unknown method: ' . get_class($this) . "::$name()");
    }

__construct() public method

Constructor.

public void __construct ( $match = null, $params = [], $config = [] )
$match | string | The MATCH expression
$params | array | Expression parameters.
$config | array | Name-value pairs that will be used to initialize the object properties

Source code

                    public function __construct($match = null, $params = [], $config = [])
    {
        $this->match = $match;
        $this->params = $params;
        parent::__construct($config);
    }

__get() public method

Defined in: yii\base\BaseObject::__get()

Returns the value of an object property.

Do not call this method directly as it is a PHP magic method that will be implicitly called when executing `$value = $object->property;`.

See also __set().

public mixed __get ( $name )
$name | string | The property name
return | mixed | The property value
throws | yii\base\UnknownPropertyException | if the property is not defined
throws | yii\base\InvalidCallException | if the property is write-only

Source code

                    public function __get($name)
    {
        $getter = 'get' . $name;
        if (method_exists($this, $getter)) {
            return $this->$getter();
        } elseif (method_exists($this, 'set' . $name)) {
            throw new InvalidCallException('Getting write-only property: ' . get_class($this) . '::' . $name);
        }
        throw new UnknownPropertyException('Getting unknown property: ' . get_class($this) . '::' . $name);
    }

__isset() public method

Defined in: yii\base\BaseObject::__isset()

Checks if a property is set, i.e. defined and not null.

Do not call this method directly as it is a PHP magic method that will be implicitly called when executing `isset($object->property)`.

Note that if the property is not defined, false will be returned.

See also https://www.php.net/manual/en/function.isset.php.

public boolean __isset ( $name )
$name | string | The property name or the event name
return | boolean | Whether the named property is set (not null).

Source code

                    public function __isset($name)
    {
        $getter = 'get' . $name;
        if (method_exists($this, $getter)) {
            return $this->$getter() !== null;
        }
        return false;
    }

__set() public method

Defined in: yii\base\BaseObject::__set()

Sets value of an object property.

Do not call this method directly as it is a PHP magic method that will be implicitly called when executing `$object->property = $value;`.

See also __get().

public void __set ( $name, $value )
$name | string | The property name or the event name
$value | mixed | The property value
throws | yii\base\UnknownPropertyException | if the property is not defined
throws | yii\base\InvalidCallException | if the property is read-only

Source code

                    public function __set($name, $value)
    {
        $setter = 'set' . $name;
        if (method_exists($this, $setter)) {
            $this->$setter($value);
        } elseif (method_exists($this, 'get' . $name)) {
            throw new InvalidCallException('Setting read-only property: ' . get_class($this) . '::' . $name);
        } else {
            throw new UnknownPropertyException('Setting unknown property: ' . get_class($this) . '::' . $name);
        }
    }

__unset() public method

Defined in: yii\base\BaseObject::__unset()

Sets an object property to null.

Do not call this method directly as it is a PHP magic method that will be implicitly called when executing `unset($object->property)`.

Note that if the property is not defined, this method will do nothing. If the property is read-only, it will throw an exception.

See also https://www.php.net/manual/en/function.unset.php.

public void __unset ( $name )
$name | string | The property name
throws | yii\base\InvalidCallException | if the property is read only.

Source code

                    public function __unset($name)
    {
        $setter = 'set' . $name;
        if (method_exists($this, $setter)) {
            $this->$setter(null);
        } elseif (method_exists($this, 'get' . $name)) {
            throw new InvalidCallException('Unsetting read-only property: ' . get_class($this) . '::' . $name);
        }
    }

addParams() public method

Adds additional parameters to be parsed into the query.

See also params().

public $this addParams ( $params )
$params | array | List of expression parameter values indexed by parameter placeholders. For example, `[':name' => 'Dan', ':age' => 31]`.
return | $this | The expression object itself

Source code

                    public function addParams($params)
    {
        if (!empty($params)) {
            if (empty($this->params)) {
                $this->params = $params;
            } else {
                foreach ($params as $name => $value) {
                    if (is_int($name)) {
                        $this->params[] = $value;
                    } else {
                        $this->params[$name] = $value;
                    }
                }
            }
        }
        return $this;
    }

andFilterMatch() public method (available since version 2.0.7)

Adds an additional MATCH condition to the existing one but ignores empty operands.

The new condition and the existing one will be joined using the 'AND' operator.

This method is similar to andMatch(). The main difference is that this method will remove empty query operands. As a result, this method is best suited for building query conditions based on filter values entered by users.

See also:

- filterMatch()
- orFilterMatch()

public $this andFilterMatch ( array $condition )
$condition | array | The new MATCH condition. Please refer to match() on how to specify this parameter.
return | $this | The query object itself

Source code

                    public function andFilterMatch(array $condition)
    {
        $condition = $this->filterCondition($condition);
        if ($condition !== []) {
            $this->andMatch($condition);
        }
        return $this;
    }

andMatch() public method

Adds an additional MATCH condition to the existing one.

The new condition and the existing one will be joined using the 'AND' (' ') operator.

See also:

- match()
- orMatch()

public $this andMatch ( $condition, $params = [] )
$condition | string|array|yii\db\Expression | The new MATCH condition. Please refer to match() on how to specify this parameter.
$params | array | The parameters (name => value) to be parsed into the query.
return | $this | The expression object itself

Source code

                    public function andMatch($condition, $params = [])
    {
        if ($this->match === null) {
            $this->match = $condition;
        } else {
            $this->match = ['and', $this->match, $condition];
        }
        $this->addParams($params);
        return $this;
    }

canGetProperty() public method

Defined in: yii\base\BaseObject::canGetProperty()

Returns a value indicating whether a property can be read.

A property is readable if:

- the class has a getter method associated with the specified name (in this case, property name is case-insensitive);
- the class has a member variable with the specified name (when `$checkVars` is true);

See also canSetProperty().

public boolean canGetProperty ( $name, $checkVars = true )
$name | string | The property name
$checkVars | boolean | Whether to treat member variables as properties
return | boolean | Whether the property can be read

Source code

                    public function canGetProperty($name, $checkVars = true)
    {
        return method_exists($this, 'get' . $name) || $checkVars && property_exists($this, $name);
    }

canSetProperty() public method

Defined in: yii\base\BaseObject::canSetProperty()

Returns a value indicating whether a property can be set.

A property is writable if:

- the class has a setter method associated with the specified name (in this case, property name is case-insensitive);
- the class has a member variable with the specified name (when `$checkVars` is true);

See also canGetProperty().

public boolean canSetProperty ( $name, $checkVars = true )
$name | string | The property name
$checkVars | boolean | Whether to treat member variables as properties
return | boolean | Whether the property can be written

Source code

                    public function canSetProperty($name, $checkVars = true)
    {
        return method_exists($this, 'set' . $name) || $checkVars && property_exists($this, $name);
    }

className() public static method
Deprecated since 2.0.14. On PHP >=5.5, use `::class` instead.

Defined in: yii\base\BaseObject::className()

Returns the fully qualified name of this class.

public static string className ( )
return | string | The fully qualified name of this class.

Source code

                    public static function className()
    {
        return get_called_class();
    }

filterCondition() protected method (available since version 2.0.7)

Removes empty operands from the given query condition.

protected array filterCondition ( $condition )
$condition | array | The original condition
return | array | The condition with empty operands removed.

Source code

                    protected function filterCondition($condition)
    {
        if (!is_array($condition)) {
            return $condition;
        }
        if (!isset($condition[0])) {
            // hash format: 'column1' => 'value1', 'column2' => 'value2', ...
            foreach ($condition as $name => $value) {
                if ($this->isEmpty($value)) {
                    unset($condition[$name]);
                }
            }
            return $condition;
        }
        // operator format: operator, operand 1, operand 2, ...
        $operator = array_shift($condition);
        switch (strtoupper($operator)) {
            case 'NOT':
            case 'AND':
            case 'OR':
                foreach ($condition as $i => $operand) {
                    $subCondition = $this->filterCondition($operand);
                    if ($this->isEmpty($subCondition)) {
                        unset($condition[$i]);
                    } else {
                        $condition[$i] = $subCondition;
                    }
                }
                if (empty($condition)) {
                    return [];
                }
                break;
            case 'SENTENCE':
            case 'PARAGRAPH':
                $column = array_shift($condition);
                foreach ($condition as $i => $operand) {
                    if ($this->isEmpty($operand)) {
                        unset($condition[$i]);
                    }
                }
                if (empty($condition)) {
                    return [];
                }
                array_unshift($condition, $column);
                break;
            case 'ZONE':
            case 'ZONESPAN':
                foreach ($condition as $i => $operand) {
                    if ($this->isEmpty($operand)) {
                        unset($condition[$i]);
                    }
                }
                if (empty($condition)) {
                    return [];
                }
                break;
            default:
                if (array_key_exists(1, $condition) && $this->isEmpty($condition[1])) {
                    return [];
                }
        }
        array_unshift($condition, $operator);
        return $condition;
    }

filterMatch() public method (available since version 2.0.7)

Sets the MATCH part of the query but ignores empty operands.

This method is similar to match(). The main difference is that this method will remove empty query operands. As a result, this method is best suited for building query conditions based on filter values entered by users.

The following code shows the difference between this method and match():

    // MATCH (@title :title)
    $query->filterMatch(['name' => null, 'title' => 'foo']);
    // MATCH (@title :title)
    $query->match(['title' => 20]);
    // MATCH (@name :name @title :title)
    $query->match(['name' => null, 'age' => 20]);

Note that unlike match(), you cannot pass binding parameters to this method.

See also:

- \yii\sphinx\where()
- andFilterMatch()
- orFilterMatch()

public $this filterMatch ( array $condition )
$condition | array | The conditions that should be put in the MATCH part. See match() on how to specify this parameter.
return | $this | The query object itself

Source code

                    public function filterMatch(array $condition)
    {
        $condition = $this->filterCondition($condition);
        if ($condition !== []) {
            $this->match($condition);
        }
        return $this;
    }

hasMethod() public method

Defined in: yii\base\BaseObject::hasMethod()

Returns a value indicating whether a method is defined.

The default implementation is a call to php function `method_exists()`. You may override this method when you implemented the php magic method `__call()`.

public boolean hasMethod ( $name )
$name | string | The method name
return | boolean | Whether the method is defined

Source code

                    public function hasMethod($name)
    {
        return method_exists($this, $name);
    }

hasProperty() public method

Defined in: yii\base\BaseObject::hasProperty()

Returns a value indicating whether a property is defined.

A property is defined if:

- the class has a getter or setter method associated with the specified name (in this case, property name is case-insensitive);
- the class has a member variable with the specified name (when `$checkVars` is true);

See also:

- canGetProperty()
- canSetProperty()

public boolean hasProperty ( $name, $checkVars = true )
$name | string | The property name
$checkVars | boolean | Whether to treat member variables as properties
return | boolean | Whether the property is defined

Source code

                    public function hasProperty($name, $checkVars = true)
    {
        return $this->canGetProperty($name, $checkVars) || $this->canSetProperty($name, false);
    }

init() public method

Defined in: yii\base\BaseObject::init()

Initializes the object.

This method is invoked at the end of the constructor after the object is initialized with the given configuration.

public void init ( )

Source code

                    public function init()
    {
    }

isEmpty() protected method (available since version 2.0.7)

Returns a value indicating whether the give value is "empty".

The value is considered "empty", if one of the following conditions is satisfied:

- it is `null`,
- an empty string (`''`),
- a string containing only whitespace characters,
- or an empty array.

protected boolean isEmpty ( $value )
$value | mixed |
return | boolean | If the value is empty

Source code

                    protected function isEmpty($value)
    {
        return $value === '' || $value === [] || $value === null || is_string($value) && trim($value) === '';
    }

match() public method

Sets the MATCH expression.

The method requires a `$condition` parameter, and optionally a `$params` parameter specifying the values to be parsed into the expression.

The `$condition` parameter should be either a string (e.g. `'@name "John"'`) or an array.

See also:

- andMatch()
- orMatch()

public $this match ( $condition, $params = [] )
$condition | string|array|yii\db\Expression | The conditions that should be put in the MATCH expression.
$params | array | The parameters (name => value) to be parsed into the query.
return | $this | The expression object itself

Source code

                    public function match($condition, $params = [])
    {
        $this->match = $condition;
        $this->addParams($params);
        return $this;
    }

orFilterMatch() public method (available since version 2.0.7)

Adds an additional MATCH condition to the existing one but ignores empty operands.

The new condition and the existing one will be joined using the 'OR' operator.

This method is similar to orMatch(). The main difference is that this method will remove empty query operands. As a result, this method is best suited for building query conditions based on filter values entered by users.

See also:

- filterMatch()
- andFilterMatch()

public $this orFilterMatch ( array $condition )
$condition | array | The new MATCH condition. Please refer to match() on how to specify this parameter.
return | $this | The query object itself

Source code

                    public function orFilterMatch(array $condition)
    {
        $condition = $this->filterCondition($condition);
        if ($condition !== []) {
            $this->orMatch($condition);
        }
        return $this;
    }

orMatch() public method

Adds an additional MATCH condition to the existing one.

The new condition and the existing one will be joined using the 'OR' ('|') operator.

See also:

- match()
- andMatch()

public $this orMatch ( $condition, $params = [] )
$condition | string|array|yii\db\Expression | The new WHERE condition. Please refer to match() on how to specify this parameter.
$params | array | The parameters (name => value) to be parsed into the query.
return | $this | The expression object itself

Source code

                    public function orMatch($condition, $params = [])
    {
        if ($this->match === null) {
            $this->match = $condition;
        } else {
            $this->match = ['or', $this->match, $condition];
        }
        $this->addParams($params);
        return $this;
    }

params() public method

Sets the parameters to be parsed into the query.

See also addParams().

public $this params ( $params )
$params | array | List of expression parameter values indexed by parameter placeholders. For example, `[':name' => 'Dan', ':age' => 31]`.
return | $this | The expression object itself

Source code

                    public function params($params)
    {
        $this->params = $params;
        return $this;
    }