Фильтрация в запросах #

Описание #

В основном фильтр передается в запросах https://api.apiship.ru/v1/lists/* в качестве GET-параметра. По фильтру можно получить определенную запись по условию из фильтра. Пример фильтра, https://api.apiship.ru/v1/lists/points?filter=city=Москва;providerKey=cdek. Этим запросом пользователь получит точки ПВЗ СДЭК по городу Москва.

Синтаксис #

Эта строка filter=city=Москва;providerKey=cdek называется фильтром, то что содержится внутри фильтра называется условие[ями]. Например, этот фильтр содержит условия city=Москва и providerKey=cdek.

Условие состоит из 3 секций: ключ, оператор, значение. Таким образом условие city=Москва можно разделить на секции:

Ключ - city
Оператор - =
Значение - Москва

Каждое следующие условие должно быть конкатенировано к фильтру через разделитель ;. Такой фильтр валиден filter=city=Москва;providerKey=cdek, а такой уже нет filter=city=Москва;providerKey=cdek;.

Таблица доступных значений:

Тип	Пример	Примечание
Array	`[one,two,three]`	Если в массиве больше 1 значения может использоваться только оператор `=`. Внутри массива разделитель `,`.
String	`one` `'one'` `"one"`	В качестве значения String может быть обрамлен в кавычки `'` или `"`.
Number	`0` `0.1`

Таблица доступных операторов:

Оператор	Доступные типы	Описание
`=`	`Array`, `String`, `Number`
`>`	`Number`, `String`
`<`	`Number`, `String`
`%`	`Number`, `String`	Поиск по частям. Оператор работает как LIKE “%значение%” в SQL

Пример реализации #

 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
<?php
 
// Массив условий для фильтра.
$conditions = [
    [
        'key'      => 'city',
        'operator' => '=',
        // Тип значения String
        'value'    => 'Москва'
    ],
    [
        'key'      => 'providerKey',
        'operator' => '=',
        // Тип значения Array
        'value'    => ['cdek','boxberry']
    ],
];
// Массив условий в виде строки.
$stringConditions = [];
foreach($conditions as $condition){
    $key = $condition['key'];
    $operator = $condition['operator'];
    $value = $condition['value'];
 
    $stringConditions[] = sprintf(
        // Шаблон для печати 3-х секций.
        '%s%s%s',
        // 1 секция: ключ.
        $key,
        // 2 секция: оператор.
        $operator,
        // 3 секция: значение. Если тип Array, то печатаем как "[<значения через ,>]", иначе печатаем "как есть".
        is_array($value) ? sprintf('[%s]',implode(',',$value)) : $value
    );
}
// Печатаем фильтр, все условия конкатенируются друг к другу через разделитель (;).
$filter = sprintf('filter=%s',implode(';',$stringConditions));
// В итоге получим фильтр: "filter=city=Москва;providerKey=[cdek,boxberry]".
echo $filter;