Class yii\sphinx\MatchExpression

All Classes | Properties | Methods
Inheritanceyii\sphinx\MatchExpression » yii\base\BaseObject
Available since extension's version2.0.6
Source Code https://github.com/yiisoft/yii2-sphinx/blob/master/src/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:

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
__construct() Constructor. yii\sphinx\MatchExpression
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
filterMatch() Sets the MATCH part of the query but ignores empty operands. yii\sphinx\MatchExpression
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

__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

 

                public function __construct($match = null, $params = [], $config = [])
{
    $this->match = $match;
    $this->params = $params;
    parent::__construct($config);
}
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

 

                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:

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

 

                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:

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

 

                public function andMatch($condition, $params = [])
{
    if ($this->match === null) {
        $this->match = $condition;
    } else {
        $this->match = ['and', $this->match, $condition];
    }
    $this->addParams($params);
    return $this;
}
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.

 

                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:

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

 

                public function filterMatch(array $condition)
{
    $condition = $this->filterCondition($condition);
    if ($condition !== []) {
        $this->match($condition);
    }
    return $this;
}
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

 

                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:

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

 

                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:

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

 

                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:

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

 

                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

 

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