mnemesong/spex

• The documentation is written in two languages: Russian and English.
• Документация написана на двух языках: русском и английском.

---

General description / Общее описание

ENG:

The package provides objects and an interface for expression of specifications (describes the conditions for fetching records from storage). For quick construction, use Sp::ex() builder.

RUS:

Пакет предоставляет объекты и интерфейс для выражения спецификаций (описывают услоние выборки записей из хранилища). Для быстрого построения используется билдер Sp::ex()

---

Requirements / Требования

• PHP >= 7.4
• Composer >=2.0

---

Installation / Установка

composer require "mnemesong/spex"

---

Specifications / Спецификации

ENG:

Specifications allow you to specify a condition for searching or selecting records, including logically complex ones.

Specifier Sp::ex

The ex() method of class Sp allows you to quickly express any specification of various types. Its general syntax looks like as follows

Sp::ex(<spec character>, <column name>, <additional comparison parameter(column name, value or null)>);

Additional type parameter depends on the specification type. There are several types of specifications:

Array comparison specifications

They have the general form: Sp::ex(string <spec mark>, string <column name>, array <comparison array>)

Types of array comparison specifications:

• "in" - checks whether the value in the column is included in the comparison array
• "!in" - checks whether the value in the column is not included in the comparison array

Example:

Sp::ex("in", "age", [11, 22, 33, 44, 55])

Table column comparison specifications

Have a general form: Sp::ex(string <spec mark>, string <column name>, string <column name>)

Table column comparison specification types:

• "cs=" - checks the equality of values in two columns of the same table row as strings (character by character)
• "cs!=" - checks the inequality of values in two columns of the same table row as strings (character by character)
• "cs>", "cs!>", "cs>=", "cs<", "cs!<", "cs<="- compare values in two columns of one table row as strings (character by character)
• "clike" - checks whether the value of the second column of the string is included in the first column as a substring
• "c!like" - checks whether the value of the second column of the string is тще included in the first column as a substring
• "cn=" - checks the equality of values in two columns of the same table row as numbers
• "cn!=" - checks the inequality of values in two columns of the same table row as numbers
• "cn>", "cn!>", "cn>=", "cn<", "cn!<", "cn<=" - compare values in two columns of the same table row as numbers

Example:

Sp::ex("cs<=", "contractsCount", "requestsCount")

Number Comparison Specifications

They have the general form: Sp::ex(string <spec character>, string <column name>, float|int|stringNumber <numerical value>)

Comparison specification types with numeric value:

• "n=" - checks for equality (not NULL-safe) of a column value with a specified numeric value
• "n!=" - checks for inequality (non-NULL-safe) values of a column with a specified numeric value
• "n>", "n!>", "n>=", "n<", "n!<", "n<=" - compares the value of the column with the specified numeric value

Example:

Sp::ex("n=", "winsCount", "losesCount")

String comparison specifications

They have the general form: Sp::ex(string <spec character>, string <column name>, string <string value>)

Comparison specification types with string value:

• "s=" - checks for equality (not NULL-safe) of a column value with the specified string value
• "s!=" - checks if the value of the column with the specified string value is not NULL-safe
• "s>", "s!>", "s>=", "s<", "s!<", "s<=" - compare character by character values of the column with the specified string value
• "like" - checks if a string value is a substring of a value in a column

Example:

Sp::ex("s=", "name", "Bob")

Unary Comparison Specifications

They have a general form: Sp::ex(string <spec mark>, string <column name>)

Unary comparison specification types:

• "null" - checks if the value of the column is NULL
• "!null" - checks if the column value is null
• "empty" - checks for equality in a NULL column or an empty string
• "!empty" - checks if value is not NULL column or empty string

Example:

Sp::ex("empty", "comment")

Complex compound specifications

They have the general form: Sp::ex(string <spec mark>, SpecificationInterface[] < array of child specifications>)

Types of complex compound specifications:

• "and" - specifications correspond to entries for which all conditions specified are met in child specifications
• "and" - specifications correspond to the record for which one of the conditions specified will be met in child specifications

Example:

Sp::ex("and", [Sp::ex("!empty", "birthday"), Sp::ex("!empty", "age")])

Unary compound specifications

They have the general form: Sp::ex(string <spec mark>, SpecificationInterface <child specification>)

Unary compound specification types:

• "!" is a non-null-safe negation of a child specification.

Example:

Sp::ex("!", Sp::ex("c=", "managerUuid", "customerUuid"))

RUS:

Спецификации позволяют указывать условие для поиска или отбора записей, в том числе логически сложные.

Выразитель спецификаций Sp::ex

Метод ex() класса Sp позволяет быстро выражать любые спецификации различных типов. Его общий синтаксис выгляди следующим образом

Sp::ex(<знак спецификации>, <имя колонки>, <доп. параметр сравнения(имя колонки, значеие или null)>);

Тип доп. параметра зависит от типа спецификации. Существует несколько типов спецификаций:

Спецификации сравнения с массивом

Имеют общий вид: Sp::ex(string <знак спецификации>, string <имя колонки>, array <массив сравнения>)

Типы спецификаций сравнения с массивом:

• "in" - проверяет вхождение значения в колонке в массив сравнения
• "!in" - проверяет отсутствие вхождения значения в колонке в массив сравнения

Пример:

Sp::ex("in", "age", [11, 22, 33, 44, 55])

Спецификации сравнения колонок таблицы

Имеют общий вид: Sp::ex(string <знак спецификации>, string <имя колонки>, string <имя колонки>)

Типы спецификаций сравнения колонок таблицы:

• "cs=" - проверяет равенство значений в двух колонках одной строки таблицы как строк (посимвольно)
• "cs!=" - проверяет неравенство значений в двух колонках одной строки таблицы как строк (посимвольно)
• "cs>", "cs!>", "cs>=", "cs<", "cs!<", "cs<=" - сравнивают значений в двух колонках одной строки таблицы как строк (посимвольно)
• "clike" - проверяет вхождение значения второй колонки строки в первую в качестве подстроки
• "c!like" - проверяет отсутствие вхождения значения второй колонки строки в первую в качестве подстроки
• "cn=" - проверяет равенство значений в двух колонках одной строки таблицы как чисел
• "cn!=" - проверяет неравенство значений в двух колонках одной строки таблицы как чисел
• "cn>", "cn!>", "cn>=", "cn<", "cn!<", "cn<=" - сравнивают значений в двух колонках одной строки таблицы как чисел

Пример:

Sp::ex("cs<=", "contractsCount", "requestsCount")

Спецификации сравнения c числовым значением

Имеют общий вид: Sp::ex(string <знак спецификации>, string <имя колонки>, float|int|stringNumber <числовое значение>)

Типы спецификаций сравнения c числовым значением:

• "n=" - проверяет равенство (не NULL-безопасное) значения колонке с указанным числовым значением
• "n!=" - проверяет неравенство (не NULL-безопасное) значения колонке с указанным числовым значением
• "n>", "n!>", "n>=", "n<", "n!<", "n<=" - сравнивает значения колонке с указанным числовым значением

Пример:

Sp::ex("n=", "winsCount", "losesCount")

Спецификации сравнения cо строковым значением

Имеют общий вид: Sp::ex(string <знак спецификации>, string <имя колонки>, string <строковое значение>)

Типы спецификаций сравнения cо строковым значением:

• "s=" - проверяет равенство (не NULL-безопасное) значения колонке с указанным строковым значением
• "s!=" - проверяет неравенство (не NULL-безопасное) значения колонке с указанным строковым значением
• "s>", "s!>", "s>=", "s<", "s!<", "s<=" - сравнивает посимвольно значения колонке с указанным строковым значением
• "like" - проверяет вхождение строкового значения в значение в колонке в качестве подстроки

Пример:

Sp::ex("s=", "name", "Bob")

Спецификации унарного сравнения

Имеют общий вид: Sp::ex(string <знак спецификации>, string <имя колонки>)

Типы спецификаций унарного сравнения:

• "null" - проверяет равенство значения колонке NULL
• "!null" - проверяет неравенство значения колонке NULL
• "empty" - проверяет равенство значения в колонке NULL или пустой строке
• "!empty" - проверяет неравенство значения колонке NULL или пустой строке

Пример:

Sp::ex("empty", "comment")

Сложные составные спецификации

Имеют общий вид: Sp::ex(string <знак спецификации>, SpecificationInterface[] <массив дочерних спецификаций>)

Типы сложных составных спецификаций:

• "and" - спецификации отвечают записи для которых выполняются все условия, указанные в дочерних спецификациях
• "and" - спецификации отвечают записи для которых выполнется , одно из условий, указанных в дочерних спецификациях

Пример:

Sp::ex("and", [Sp::ex("!empty", "birthday"), Sp::ex("!empty", "age")])

Унарные составные спецификации

Имеют общий вид: Sp::ex(string <знак спецификации>, SpecificationInterface <дочерняя спецификация>)

Типы унарных составных спецификаций:

• "!" - не Null-безопасное отрицание дочерней спецификации.

Пример:

Sp::ex("!", Sp::ex("c=", "managerUuid", "customerUuid"))

---

Converting Structures to Specifications / Преобразование структур в спецификации

ENG

The class Sp allows you to turn Structures into specifications. This is useful when you need to check in some repository the presence of records in many respects similar to a specific structure. Use the Sp::st()

method for this

Example

$struct = new Structure(['name' => 'Victoria', 'age' => 21]);
$spec = Sp::st($struct, 'and');
// The result will be equivalent to the following code:
$spec = Sp::ex('and', [
 Sp::ex('s=', 'name', 'Victoria')
 Sp::ex('s=', 'age', '21');
]);

RUS

Класс Sp позволяет превращать Структуры в спецификации. Это полезно когда нужно проверить в каком-то хранилище наличие записей по многим параметрам похожих на конкретную структуру. Используйте для этого метод Sp::st()

Пример

$struct = new Structure(['name' => 'Victoria', 'age' => 21]);
$spec = Sp::st($struct, 'and');
// Результат будет эквивалентен следующему коду:
$spec = Sp::ex('and', [
 Sp::ex('s=', 'name', 'Victoria')
 Sp::ex('s=', 'age', '21');
]);

License / Лицензия

- MIT

---

Contacts / Контакты

- Anatoly Starodubtsev "Pantagruel74" - tostar74@mail.ru