1. Документация
  2. Для разработчика сайта
  3. Функции и классы
  4. Встроенные классы

Класс Query

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

Простой пример

  1. Допустим, мы кликнули по ссылке: href="?page=2&a=11&b=22&c=33"
  2. Допустим нам нужны только параметры a и b.
    На целевой странице захватываем эти параметры: Query::capture('a&b');
  3. Конструируем ссылку на следующую страницу: $href='?page=3&'.Query::build();

При построении URL обычным путем, путем добавления параметров к ссылкам с помощью $_GET[], нужно помнить, был ли уже добавлен тот или иной параметр. Удаление параметра тем более затруднено.

Класс Query позволяет последовательно формировать сложные параметрические URL-запросы по ходу кода. Вы делаете простые шаги, не беспокоясь о возможных накладках.

Может показаться, что данный способ формирования URL слишком сложен, так как нужно использовать несколько методов класса. Действительно, для простых запросов применять данный класс не имеет смысла, но вы оцените его по достоинству при сложных запросах, например, при построении фильтров товаров интернет-магазина.

Query::capture($params=null)

Захват нескольких параметров (пакета параметров), поступивших на страницу через URL. Если URL поступает в виде ЧПУ, то оно будет преобразовано в параметрическое.

  • $params — нужные параметры в виде параметрической строки или массива. Если параметр опущен, из URL захватываются все параметры. Сами значения параметров из массива $params ни на что не влияют.

Примеры: 

Query::capture(); //Захватываются все параметры из URL.

Query::capture('a&b[2]');
/* или с помощью массива:
$params['a'] = '';
$params['b'][2] = '';          
Query::capture($params);*/

Query::add($params)

Добавление/изменение параметров в пакете

  • $params — нужные параметры со значениями в виде параметрической строки или массива.

Примеры: 

Query::add('a=11&b[2]=22');
/* или с помощью массива:
$params['a'] = 11;
$params['b'][2] = 22;
Query::add($params); */

Query::set($params)

Формирование пакета параметров "с нуля". Аналогично методу Query::add(), только предварительно сбрасывается (удаляется) существовавший до этого пакет параметров. Естественно, вызывать в начале метод Query::capture() здесь не нужно.

Query::get($param=null)

Извлечение параметров из пакета

  • Возвращает значение параметра/параметров. Значение может оказаться и массивом.
  • $param — параметр в виде параметрической строки или массива. Сами значения параметров из массива $params ни на что не влияют.

Примеры: 

Query::get(); //Получить все параметры пакета.
Query::get('a'); //Получить значение параметра из пакета. 
Query::get('b[2]');

# C помощью параметра-массива можно получить все параметры за один вызов метода:
$params['a'] = '';
$params['b'][2] = '';          
Query::capture($params);

Query::remove($params)

Удаление параметров из пакета

  • $params — перечень удаляемых из пакета параметров в виде параметрической строки или массива. Сами значения параметров из массива $params ни на что не влияют.

Примеры: 

Query::remove('a&b[2]');
/* или с помощью массива:
$params['a'] = '';
$params['b'][2] = '';         
Query::remove($params); */

Query::build($attachments=null, $detachments=null)

Два параметра: $attachments и $detachments позволяют изменить вывод в последний момент, не затрагивая базового пакета параметров.

  • Возвращает строку пакета url-параметров для добавления к ссылке. Строка всегда начинается с имени параметра, но не с '?' или '&', то есть, нужный знак нужно дописывать.
  • $attachments — параметры (со значениями), которые нужно добавить к данной ссылке
  • $detachments — параметры, которые нужно убрать из данной ссылки. Сами значения параметров из массива $detachments ни на что не влияют.

Примеры: 

$href = '?page=4&'.Query::build('a=aa&b[1]=bb&b[2]=bbb','x&y[3]');
/* или с помощью массива:
$attachments['a'] = 'aa';
$attachments['b'][2] = 'aa';
$attachments['b'][2] = 'aaa';
$detachments['x'] = '';
$detachments['y'][3] = '';
$href = '?page=4&'.Query::build($attachments, $detachments); */

Все параметры автоматически сортируются в алфавитном порядке со следующими исключениями:

  • Параметр, который в url шел после '?' (имя скрипта) всегда остается в начале (это могут быть: page, block и другие служебные скрипты).
  • Запрос page ставится на первое место.
  • Запрос '&block=...' ставится на второе место (если это не вывод блока: '?block=...').
  • Элементы параметра-массива sort внутри массива не сортируются и ставятся в конце.
  • Параметры part или single ставятся в самом конце строки (вместе они обычно не применяются, но если решите применять оба, то в конце ставить параметр single).

Кодировка параметров

Если значения параметров могут содержать спецсимволы URL, то при построении ссылки такие значения нужно кодировать. 

$href = '?page=4&'.Query::build('site='.urlencode('bloxcms.net/documentation/'));

Примечания

  • Пакет параметров существует на сайте в одном экземпляре. Если нужен второй пакет, то его придется делать обычным способом в отдельной переменной.
  • Перед использованием класса, Вы должны определиться какие url-параметры вы будете протаскивать этим методом. Таскать все параметры нет смысла — это только усложнит работу, ведь вам придется не только добавлять параметры, но и удалять их.
  • Все значения обрабатываются с помощью метода Sql::sanitize().