Selector - протокол выборки данных

Описание

Selector - механизм формирования выборок, который должен заменить использование umiSelection+umiSelectionParser. Замена механизма выборок вызвана желанием максимально упростить выборки, избавиться от необходимости использования дополнительных классов и упростить определение искомых полей.

Использование

Определение результата выборки

При создании экземпляра класса selector необходимо определить, что мы собираемся получить в результате выборки: список объектов (umiObject) или список страниц (umiHierarchyElement). Для этого в конструктор нужно передать строку 'objects', либо 'pages' соответственно.

$pages = new selector('pages');

Если не задать результат выборки, то будет выброшено исключение selectorException.

Фильтрация по значениям свойств

Методы фильтрации

• equals - поиск точного вхождения строки, либо числа

$users->where('login')->equals('lyxsus');

• like - поиск по подстроке

$users->where('login')->like('lyx%');

• ilike - поиск по подстроке без учета регистра
• more - поиск ">" ("больше")

$users->where('last_request_time')->more(time() - 3600);

• eqmore - поиск ">=" ("больше, либо равно")
• less - поиск "<" ("меньше")

$users->where('last_request_time')->less(time() - 3600);

• eqless - поиск "<=" ("меньше, либо равно")
• between - поиск по интервалу

$users->where('last_request_time')->between(time() - 3600, time());

• isnull - поиск по нулевому значению (NULL)

$users->where('is_activated')->isnull(true);  // WHERE ... IS NULL
$users->where('is_activated')->isnull(false);  // WHERE ... IS NOT NULL

Собственные свойства объектов и страниц

Свойства определяются по названию поля и типам данных, заданных методом 'types()'. Если поле не найдено в ни в одном из типов, то будет выброшено исключение selectorException. Естественно, если не задать ни одного типа данных, то исключение будет гарантированно выброшено, не считая тех случаев, когда мы ищем по системному полю.

Системные свойства объектов

• name - название объекта. По умолчанию ищет любое название.
• owner- владелец объекта (создатель). По умолчанию ищет страницы любого владельца.
• * - особый способ поиска - по всем возможным свойствам. Ищется вхождение хотя бы по одному свойству объекта.

Системные свойства страниц

• name - название страницы. По умолчанию ищет любое название.
• owner - владелец страницы (создатель). По умолчанию ищет страницы любого владельца.
• domain - домен, в котором находится страница. По умолчанию используется текущий домен. Если передать false, поиск будет произведен по всем доменам.
• lang - язык, в котором находится страница. По умолчанию используется текущий язык. Если передать false, поиск будет произведен по всем языкам.
• is_deleted - флаг удаленной страницы. По умолчанию ищет только неудаленные страницы.
• is_active - флаг активности страница. По умолчанию на стороне сайта ищет только активные страницы, в административном интерфейсе - любые страницы.
• is_visible - флаг видимости страницы. По умолчанию не учитывается.
• updatetime - время последнего обновления страницы. По умолчанию не учитывается.
• is_default - флаг главной страницы. По умолчанию не учитывается.
• template_id - шаблон страницы. По умолчанию не учитывается.
• * - особый способ поиска - по всем возможным свойствам. Ищется вхождение хотя бы по одному свойству страницы.

Сортировка

Системные свойства объектов

• name - сортировать по названию объекта.
• rand - сортировать в случайном порядке.
• ord - реализация этого способа еще не утверждена.

Системные свойства страниц

• ord - сортировать по порядку страницы, выставленному в структуре сайта (при помощи drag&drop'а).
• name - сортировать по названию страницы.
• rand - сортировать в случайном порядке.

Опции выборки

• root - выбрать только страницы, которые находятся в корне сайта, либо не вложены в страницы, перечисленные в types('hierarchy-types')
• exclude-nested - исключить из результатов выборки страницы, которые являются подстраницами страниц, входящих в выборку. Т.е. будут убраны все вложенные страницы.

Получение результатов

Чтобы получить кол-во результатов, можно вызвать метод result(), либо обратиться к свойству result (который через getter вызовет тот же result()). Сам класс selector реализует ArrayIterator, поэтому сам экземпляр selector'а можно использовать в foreach:

$pages = new selector('pages');
foreach($pages as $page) echo $page->name, "\n";

Получение количества результатов осуществляется через метод length(), либо свойство length. Метод length() возвращает количество результатов без учета LIMIT. Если в config.ini опция selection-calc-found-rows-disable равна 0, то при получении результатов и количества результатов разумнее сначала выполнять result(), а потом length() - будет использована опция SQL_CALC_FOUND_ROWS, что может положительно сказаться на производительности в большинстве случаев.

Примеры

Простые выборки - объекты

Получение всех пользователей

$users = new selector('objects');
$users->types('object-type')->name('users', 'user');

foreach($users as $user) echo $user->login, "\n";
echo "Total users", $users->length;

Поиск по свойству

$users = new selector('objects');
$users->types('object-type')->name('users', 'user');
$users->where('login')->equals('lyxsus');

foreach($users as $user) echo $user->login, "\n";
echo "Total users", $users->length;

Сортировка

$users = new selector('objects');
$users->types('object-type')->name('users', 'user');
$users->where('login')->like('l%');
$users->order('last_request_time')->desc();

foreach($users as $user) echo $user->login, "\n";
echo "Total users", $users->length;

Случайная сортировка

$users = new selector('objects');
$users->types('object-type')->name('users', 'user');
$users->order('rand');

foreach($users as $user) echo $user->login, "\n";
echo "Total users", $users->length;

Выборки страниц

Все страницы

$pages = new selector('pages');

foreach($pages as $page) {
    echo "<a href='{$page->link}'>{$page->name}</a>\n";
}

echo "Pages found: " . $pages->length;

Все объекты каталога

$pages = new selector('pages');
$pages->types('hierarchy-type')->name('catalog', 'object');

foreach($pages as $page) {
    echo "<a href='{$page->link}'>{$page->name}</a>\n";
}

echo "Pages found: " . $pages->length;

Все страницы в разделе XXX

$pages = new selector('pages');
$pages->where('hierarchy')->page('/katalog/')->childs(3);

foreach($pages as $page) {
    echo "<a href='{$page->link}'{$page->name}</a>\n";
}

echo "Pages found: " . $pages->length;

Фильтрация по правам

$pages = new selector('pages');
$pages->where('permissions')->owners(2373)->level(0x1);

foreach($pages as $page) {
    echo "<a href='{$page->link}'{$page->name}</a>\n";
}

echo "Pages found: " . $pages->length;

Опция - exclude-nested

$pages = new selector('pages');
$pages->types('hierarchy-type')->name('news', 'rubric');
$pages->types('hierarchy-type')->name('news', 'item');
$pages->option('exclude-nested', true);

foreach($pages as $page) {
    echo "<a href='{$page->link}'>{$page->name}</a>\n";
}

echo "Pages found: " . $pages->length;

Опция - root

$pages = new selector('pages');
$pages->types('hierarchy-type')->name('news', 'rubric');
$pages->types('hierarchy-type')->name('news', 'item');
$pages->option('root', true);

foreach($pages as $page) {
//синтаксическая ошибка не стравить, глюк wiki
    echo "<a href='{$page->link}'>{$page->name}</a>\n";
}

echo "Pages found: " . $pages->length;

Поиск по всем свойствам

$pages = new selector('pages');
$pages->types('hierarchy-type')->name('content', 'page');
$pages->where('*')->equals('cms');

foreach($pages as $page) {
    echo "<a href='{$page->link}'>{$page->name}</a>\n";
}

echo "Pages found: " . $pages->length;

Поиск по свойствам типа optioned

$pages = new selector('pages');
$pages->types('hierarchy-type')->name('catalog', 'object');
$pages->where('stores_state')->equals(array('int' => 123));

foreach($pages as $page) {
    echo "<a href='{$page->link}'>{$page->name}</a>\n";
}

echo "Pages found: " . $pages->length;

Ограничение кол-ва результатов выборки

$pages = new selector('pages');
$pages->limit(10, 0); //limit, offset

foreach($pages as $page) {
    echo "<a href='{$page->link}'>{$page->name}</a>\n";
}

echo "Pages found: " . $pages->length;

Изменение домена поиска

$pages = new selector('pages');
$pages->where('domain')->equals(false); // Искать во всех доменах
$pages->where('lang')->equals(false); // Искать во всех языковых версиях

foreach($pages as $page) {
    echo "<a href='{$page->link}'>{$page->name}</a>\n";
}

echo "Pages found: " . $pages->length;