/
MatchExpression.php
405 lines (380 loc) · 13 KB
/
MatchExpression.php
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
<?php
/**
* @link https://www.yiiframework.com/
* @copyright Copyright (c) 2008 Yii Software LLC
* @license https://www.yiiframework.com/license/
*/
namespace yii\sphinx;
use yii\base\BaseObject;
use yii\db\Expression;
/**
* MatchExpression represents a MATCH SphinxQL expression.
* In conjunction with [[MatchBuilder]] this class provides ability to build sophisticated MATCH expressions.
* Instance of this class can be passed to [[Query::match()]].
* For example:
*
* ```php
* 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:
*
* ```php
* 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:
*
* ```php
* 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 [[Connection::escapeMatchValue()]].
*
* @see MatchBuilder
* @see https://sphinxsearch.com/docs/current.html#extended-syntax
*
* @author Paul Klimov <klimov.paul@gmail.com>
* @since 2.0.6
*/
class MatchExpression extends BaseObject
{
/**
* @var string|array|Expression 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 match()
*/
public $match;
/**
* @var array list of match expression parameter values indexed by parameter placeholders.
* For example, `[':name' => 'Dan', ':age' => 31]`.
* These parameters will be automatically escaped using [[Connection::escapeMatchValue()]] and inserted into MATCH
* expression as a quoted strings.
*/
public $params = [];
/**
* Constructor.
* @param string $match the MATCH expression
* @param array $params expression parameters.
* @param array $config 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);
}
/**
* 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.
*
* @param string|array|Expression $condition the conditions that should be put in the MATCH expression.
* @param array $params the parameters (name => value) to be parsed into the query.
* @return $this the expression object itself
* @see andMatch()
* @see orMatch()
*/
public function match($condition, $params = [])
{
$this->match = $condition;
$this->addParams($params);
return $this;
}
/**
* Adds an additional MATCH condition to the existing one.
* The new condition and the existing one will be joined using the 'AND' (' ') operator.
* @param string|array|Expression $condition the new MATCH condition. Please refer to [[match()]]
* on how to specify this parameter.
* @param array $params the parameters (name => value) to be parsed into the query.
* @return $this the expression object itself
* @see match()
* @see orMatch()
*/
public function andMatch($condition, $params = [])
{
if ($this->match === null) {
$this->match = $condition;
} else {
$this->match = ['and', $this->match, $condition];
}
$this->addParams($params);
return $this;
}
/**
* Adds an additional MATCH condition to the existing one.
* The new condition and the existing one will be joined using the 'OR' ('|') operator.
* @param string|array|Expression $condition the new WHERE condition. Please refer to [[match()]]
* on how to specify this parameter.
* @param array $params the parameters (name => value) to be parsed into the query.
* @return $this the expression object itself
* @see match()
* @see andMatch()
*/
public function orMatch($condition, $params = [])
{
if ($this->match === null) {
$this->match = $condition;
} else {
$this->match = ['or', $this->match, $condition];
}
$this->addParams($params);
return $this;
}
/**
* Sets the parameters to be parsed into the query.
* @param array $params list of expression parameter values indexed by parameter placeholders.
* For example, `[':name' => 'Dan', ':age' => 31]`.
* @return $this the expression object itself
* @see addParams()
*/
public function params($params)
{
$this->params = $params;
return $this;
}
/**
* Adds additional parameters to be parsed into the query.
* @param array $params list of expression parameter values indexed by parameter placeholders.
* For example, `[':name' => 'Dan', ':age' => 31]`.
* @return $this the expression object itself
* @see params()
*/
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;
}
/**
* Sets the MATCH part of the query but ignores [[isEmpty()|empty operands]].
*
* This method is similar to [[match()]]. The main difference is that this method will
* remove [[isEmpty()|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()]]:
*
* ```php
* // 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.
*
* @param array $condition the conditions that should be put in the MATCH part.
* See [[match()]] on how to specify this parameter.
* @return $this the query object itself
* @see where()
* @see andFilterMatch()
* @see orFilterMatch()
* @since 2.0.7
*/
public function filterMatch(array $condition)
{
$condition = $this->filterCondition($condition);
if ($condition !== []) {
$this->match($condition);
}
return $this;
}
/**
* Adds an additional MATCH condition to the existing one but ignores [[isEmpty()|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 [[isEmpty()|empty query operands]]. As a result, this method is best suited
* for building query conditions based on filter values entered by users.
*
* @param array $condition the new MATCH condition. Please refer to [[match()]]
* on how to specify this parameter.
* @return $this the query object itself
* @see filterMatch()
* @see orFilterMatch()
* @since 2.0.7
*/
public function andFilterMatch(array $condition)
{
$condition = $this->filterCondition($condition);
if ($condition !== []) {
$this->andMatch($condition);
}
return $this;
}
/**
* Adds an additional MATCH condition to the existing one but ignores [[isEmpty()|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 [[isEmpty()|empty query operands]]. As a result, this method is best suited
* for building query conditions based on filter values entered by users.
*
* @param array $condition the new MATCH condition. Please refer to [[match()]]
* on how to specify this parameter.
* @return $this the query object itself
* @see filterMatch()
* @see andFilterMatch()
* @since 2.0.7
*/
public function orFilterMatch(array $condition)
{
$condition = $this->filterCondition($condition);
if ($condition !== []) {
$this->orMatch($condition);
}
return $this;
}
/**
* Removes [[isEmpty()|empty operands]] from the given query condition.
*
* @param array $condition the original condition
* @return array the condition with [[isEmpty()|empty operands]] removed.
* @since 2.0.7
*/
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;
}
/**
* 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.
*
* @param mixed $value
* @return bool if the value is empty
* @since 2.0.7
*/
protected function isEmpty($value)
{
return $value === '' || $value === [] || $value === null || is_string($value) && trim($value) === '';
}
}