Просмотр исходного текста страницы Selector - протокол выборки данных

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

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

=== Определение результата выборки ===
При создании экземпляра класса '''selector''' необходимо определить, что мы собираемся получить в результате выборки: список объектов (umiObject) или список страниц (umiHierarchyElement). Для этого в конструктор нужно передать строку 'objects', либо 'pages' соответственно.
<source lang="php">
$pages = new selector('pages');
</source>
Если не задать результат выборки, то будет выброшено исключение '''selectorException'''.

=== Определение типов данных ===
=== Фильтрация по значениям свойств ===

==== Методы фильтрации ====
* '''equals''' - поиск точного вхождения строки, либо числа
<source lang="php">
$users->where('login')->equals('lyxsus');
</source>
* '''like''' - поиск по подстроке
<source lang="php">
$users->where('login')->like('lyx%');
</source>
* '''ilike''' - поиск по подстроке без учета регистра
* '''more''' - поиск ">" ("больше")
<source lang="php">
$users->where('last_request_time')->more(time() - 3600);
</source>
* '''eqmore''' - поиск ">=" ("больше, либо равно")
* '''less''' - поиск "<" ("меньше")
<source lang="php">
$users->where('last_request_time')->less(time() - 3600);
</source>
* '''eqless''' - поиск "<=" ("меньше, либо равно")
* '''between''' - поиск по интервалу
<source lang="php">
$users->where('last_request_time')->between(time() - 3600, time());
</source>
* '''isnull''' - поиск по нулевому значению (NULL)
<source lang="php">
$users->where('is_activated')->isnull(true);  // WHERE ... IS NULL
$users->where('is_activated')->isnull(false);  // WHERE ... IS NOT NULL
</source>

==== Собственные свойства объектов и страниц ====
Свойства определяются по названию поля и типам данных, заданных методом '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:
<source lang="php">
$pages = new selector('pages');
foreach($pages as $page) echo $page->name, "\n";
</source>

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

== Примеры ==

=== Простые выборки - объекты ===
==== Получение всех пользователей ====
<source lang="php">
$users = new selector('objects');
$users->types('object-type')->name('users', 'user');

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

==== Поиск по свойству ====
<source lang="php">
$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;
</source>

==== Сортировка ====
<source lang="php">
$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;
</source>


==== Случайная сортировка ====
<source lang="php">
$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;
</source>

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

==== Все страницы ====
<source lang="php">
$pages = new selector('pages');

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

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

==== Все объекты каталога ====
<source lang="php">
$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;
</source>

==== Все страницы в разделе XXX ====
<source lang="php">
$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;
</source>

==== Фильтрация по правам ====
<source lang="php">
$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;
</source>

==== Опция - exclude-nested ====
<source lang="php">
$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;
</source>

==== Опция - root ====
<source lang="php">
$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;
</source>

==== Поиск по всем свойствам ====
<source lang="php">
$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;
</source>

==== Поиск по свойствам типа optioned ====
<source lang="php">
$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;
</source>

==== Ограничение кол-ва результатов выборки ====
<source lang="php">
$pages = new selector('pages');
$pages->limit(0, 30); // offset, limit

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

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

==== Изменение домена поиска ====
<source lang="php">
$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;
</source>

[[Категория:API]]