Market PRO Filter – полное руководство

Введение

Market PRO Filter v.3.3.36 – это профессиональный плагин для Cotonti CMF, расширяющий стандартный модуль Market гибкой системой фильтрации товаров по произвольным параметрам. Плагин позволяет создавать неограниченное количество характеристик (мощность, ёмкость аккумулятора, бренд, особенности конструкции и многие другие), назначать им удобный тип (диапазон, выпадающий список, чекбоксы, радиокнопки) и привязывать к конкретной категории товаров. Посетитель сайта получает интуитивно понятную форму фильтра с «живыми» счётчиками, которые мгновенно пересчитываются после каждого выбора, а в карточке товара отображаются присвоенные параметры с переводом. Плагин полностью поддерживает мультиязычность (русский, украинский, английский), обеспечивает высокую производительность благодаря продуманной индексации и файловому кешированию, а также разделяет обычные и суперадминские параметры для гибкой настройки прав доступа.

Данное руководство разделено на три логические части. В первой части раскрываются теоретические основы: что такое фасетная фильтрация, как данные хранятся в базе данных и обрабатываются SQL-запросами, зачем нужны индексы и как устроена мультиязычность. Вторая часть посвящена практическому использованию на стороне фронтенда — как работает форма фильтра, как ведут себя зависимые счётчики и как выглядит представление параметров в карточке товара. Третья часть представляет собой подробную инструкцию для администратора сайта: создание, редактирование и удаление параметров, заполнение JSON-значений, настройка переводов и управление кешированием.

С 16.05.2026 плагин стал платным и купить его можно только написав мне в личку.

Бесплатная версия плагина “Фильтр товаров для Cotonti” по прежнему бесплатно доступна в открытом публичном репозитории на GitHub

Раздел 1. Теория: устройство и принцип работы

1.1 Фасетная фильтрация (Faceted Search)

Обычная последовательная фильтрация, когда каждый следующий выбранный параметр просто добавляет условие к запросу, не даёт пользователю понимания, какие значения других параметров останутся доступными после текущего выбора. Фасетная фильтрация решает эту проблему, заранее вычисляя количество товаров, которое будет найдено при добавлении любого другого фильтра к уже выбранным.

В плагине Market PRO Filter этот механизм реализован функцией marketprofilter_get_faceted_counts(). Для каждого параметра, отображаемого в форме фильтра, выполняется отдельный SQL-запрос, который подсчитывает количество товаров для всех его возможных значений с учётом всех остальных активных фильтров, кроме самого этого параметра. Таким образом, после выбора, например, напряжения аккумулятора «48V», рядом с каждой ёмкостью (например «21 А·ч») отображается число товаров, которые одновременно имеют и 48V, и данную ёмкость. Это позволяет покупателю сразу видеть, какие комбинации характеристик существуют, и избегать тупиковых ситуаций, когда фильтр не находит ни одного товара.

Для учёта выбранных значений текущего параметра (то есть при повторном выборе нескольких чекбоксов внутри одной группы) в запрос добавляется условие EXISTS, требующее, чтобы товар обладал хотя бы одним из отмеченных значений. Это реализует логику «ИЛИ» для чекбоксов и гарантирует, что счётчики внутри группы пересчитываются корректно.

1.2 Параметры и их типы

Каждый параметр описывается в таблице cot_marketprofilter_params следующими полями:

• param_id – автоинкрементный целочисленный идентификатор.
• param_name – уникальный системный код, состоящий из латинских букв, цифр и символа подчёркивания. Этот код используется в URL фильтра (filter_<код>) и как ключ в базе данных. Например: 001_03_samokat_battery_capacity.
• param_title – служебное название на языке по умолчанию (может быть переопределено через механизм интернационализации).
• param_type – один из четырёх типов: range, select, checkbox, radio.
• param_values – JSON-строка, определяющая допустимые значения параметра:
  • Для range – объект с ключами min и max, например {"min":0,"max":100}.
  • Для select, checkbox, radio – JSON-массив строк, например ["digital_display","speedometer","mobile_app"].
• param_category – код категории Market (structure_code), к которой привязан параметр. Если оставлено пустым, параметр считается «общим» и отображается во всех категориях, где есть товары.
• param_active – флаг активности (1 – параметр отображается, 0 – скрыт).
• param_superadmin – если установлен в 1, параметр не показывается и не учитывается для обычных посетителей; фильтровать по нему могут только пользователи группы администраторов (группа 5).
• param_helpinfo – текст подсказки, который может содержать HTML-теги и отображается рядом с параметром в форме фильтра и в карточке товара.

Типы параметров определяют внешний вид элемента в фильтре и способ хранения значения:

Диапазон (range) – предназначен для числовых характеристик, таких как цена, вес, мощность. В базе данных для товара сохраняется строка min-max (например, 1000-1500). При фильтрации используется разбор этой строки с помощью CAST(SUBSTRING_INDEX(...) AS DECIMAL), что позволяет сравнивать числовые границы.

Выпадающий список (select) – позволяет выбрать ровно одно значение из предопределённого перечня. В таблице значений для товара сохраняется ровно одна запись с ключом выбранной опции.

Чекбоксы (checkbox) – дают возможность отметить одновременно несколько вариантов. Для одного товара может быть создано несколько записей в cot_marketprofilter_params_values, по одной на каждую выбранную опцию. Благодаря уникальному индексу повторные вставки предотвращаются.

Радиокнопки (radio) – похожи на select, но представлены в виде переключателей. В базе хранится одна запись.

1.3 Хранение данных и индексация

Основные таблицы плагина:

• cot_marketprofilter_params – определения параметров.
• cot_marketprofilter_params_values – связка товар-параметр-значение. Содержит поля:
  • fieldmrkt_id – идентификатор товара из таблицы cot_market.
  • param_id – идентификатор параметра.
  • param_value – строковое значение (для range в формате min-max, для остальных – ключ опции).
• cot_marketprofilter_i18n – переводы заголовков, значений и подсказок для каждого языка.

Критически важным элементом производительности является индексация. На таблице значений установлен уникальный составной индекс uniq_field_param_value (fieldmrkt_id, param_id, param_value), который решает сразу несколько задач:

• Гарантирует отсутствие дубликатов.
• Ускоряет поиск при фильтрации, где условия строятся по param_id и param_value, а соединение с таблицей товаров происходит через fieldmrkt_id.
• Оптимизирует фасетные запросы с множественными INNER JOIN, так как движок MySQL может использовать индекс для быстрого доступа к строкам.

Внешние ключи FOREIGN KEY обеспечивают каскадное удаление: при удалении товара или параметра все связанные значения автоматически удаляются.

1.4 Мультиязычность

Плагин поддерживает три локали: ua (украинский), ru (русский), en (английский). Язык, на котором отображаются заголовки и значения параметров, определяется в следующем порядке приоритетов:

1. Язык текущего пользователя (Cot::$usr['lang']), если он входит в список поддерживаемых.
2. Язык по умолчанию, заданный в настройках плагина (marketprofilter_defaultlang).
3. Общий язык сайта (Cot::$cfg['defaultlang']).

Переводы хранятся в таблице cot_marketprofilter_i18n. Каждая запись содержит:

• i18n_param_id – ссылка на параметр.
• i18n_locale – код языка (ua/ru/en).
• i18n_title – локализованный заголовок.
• i18n_values – JSON-объект, содержащий перевод значений параметра. Ключи должны точно совпадать с опциями, указанными в param_values основного параметра. Например, для param_values: ["red","green"] перевод может быть {"red":"Красный","green":"Зелёный"}.
• i18n_helpinfo – перевод подсказки.

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

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

1.5 Кеширование подсчётов

Фасетные запросы потенциально ресурсоёмки, особенно при одновременном использовании нескольких фильтров. Чтобы снизить нагрузку на базу данных и ускорить отклик страницы, плагин применяет простое, но эффективное файловое кеширование.

При первом обращении к функции marketprofilter_get_faceted_counts() формируется уникальный ключ, состоящий из идентификатора параметра, текущей категории и отсортированного набора GET-параметров. Результат запроса сохраняется в виде JSON-файла в директории datas/cache/marketprofilter/. Время жизни такого кеша составляет 300 секунд (5 минут). При повторном запросе с тем же набором фильтров на протяжении этого времени данные извлекаются из файла мгновенно, минуя выполнение SQL.

Кеш автоматически сбрасывается при любом изменении товара – в хуке сохранения параметров товара (marketprofilter.market.edit.update.done.php) вызывается marketprofilter_cache_clear(), удаляющая все .cache файлы в папке плагина. Это гарантирует, что посетители всегда видят актуальные цифры после редактирования каталога.

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

1.6 Безопасность и права доступа

Плагин тщательно экранирует все данные, выводимые в HTML:

• Имена, заголовки и значения параметров пропускаются через htmlspecialchars() перед вставкой в шаблон.
• Исключение сделано для поля подсказки (param_helpinfo), которое выводится без экранирования, так как может содержать HTML и заполняется только администраторами в доверенной панели управления.

Суперадминские параметры (param_superadmin = 1) полностью скрыты от обычных пользователей:

• Функция marketprofilter_is_admin() проверяет принадлежность текущего пользователя к группе 5.
• При построении фильтра на фронте и в карточке товара такие параметры исключаются из выборки.
• В фасетных подсчётах суперадминские параметры также не участвуют, что предотвращает утечку информации о количестве товаров с ограниченными характеристиками.

Все SQL-запросы используют параметризованные выражения с плейсхолдерами, что исключает возможность SQL-инъекций.

1.7 Внедрение в Cotonti

Плагин использует штатную хуковую систему Cotonti, что гарантирует совместимость и отсутствие правок в ядре. Основные хуки:

• market.list.query – модифицирует переменные $sql_item_count и $sql_item_string, добавляя необходимые JOIN и WHERE для фильтрации списка товаров.
• market.list.tags – формирует и передаёт в шаблон блок {MARKET_FILTER_FORM} (форма фильтра) и сопутствующие переменные (MARKETFILTER_MESSAGE, MARKETFILTER_MESSAGE_CLASS).
• market.tags – добавляет в шаблон карточки товара блок {MARKET_FILTER_PARAMS} с перечнем присвоенных характеристик.
• market.edit.tags – вставляет в форму редактирования товара в админке блок {MARKET_FORM_FILTER_PARAMS} с интерфейсом назначения значений параметров.
• market.edit.update.done – обрабатывает сохранение выбранных значений параметров при обновлении товара.
• tools – регистрирует страницу администрирования плагина в разделе «Расширения».

Шаблоны плагина загружаются с учётом возможности переопределения: например, для категории electric-scooters будет сначала искаться шаблон marketprofilter.filterform.electric-scooters.tpl, а если его нет – стандартный marketprofilter.filterform.tpl. Это позволяет гибко менять дизайн фильтра для разных разделов каталога.

Раздел 2. Практика: как работает фильтр на фронтенде

2.1 Внешний вид и структура формы

На странице категории товаров форма фильтра обычно размещается в сайдбаре или над списком товаров. Она заключена в карточку Bootstrap 5 (card p-3 mb-4 rounded-2 border border-success-subtle). В правом верхнем углу расположена кнопка с иконкой вопроса, открывающая модальное окно с общей справкой по использованию фильтра.

Форма отправляется методом GET, что позволяет легко сохранять состояние фильтрации в URL и делиться ссылками. В ней скрытыми полями передаются текущая категория (c), модуль (e=market), язык (l) и флаг saveFilter=1 (при необходимости).

Каждый параметр занимает блок <div class="mb-3">. Заголовок параметра отображается жирным шрифтом; если для параметра задана подсказка, рядом с заголовком появляется иконка вопроса, открывающая отдельное модальное окно с текстом подсказки.

2.2 Поведение в зависимости от типа

Диапазон (range) – представлен ползунком <input type="range">. Над ползунком показываются минимальное значение и текущее выбранное максимальное значение (обновляется через JavaScript-функцию updateRangeValue). Стилизация выполнена с использованием CSS-переменной --value-percentage, которая позволяет закрашивать пройденную часть дорожки градиентом.

Выпадающий список (select) – стандартный <select> с дополнительной пустой опцией «---» (чтобы можно было сбросить выбор). Каждый пункт содержит текст опции и в скобках число доступных товаров, например: «48 (12)». Если опция была выбрана ранее, она получает атрибут selected.

Чекбоксы (checkbox) – каждый чекбокс обёрнут в <div class="form-check">. Рядом с меткой выводится «бейдж» с количеством товаров, если это количество больше нуля. Пример: <span class="badge rounded-pill text-bg-warning me-1">12</span>Цифровой дисплей. Отмеченные чекбоксы получают атрибут checked. Имя поля формируется как массив (name="filter_...[]"), что позволяет передавать множественные значения.

Радиокнопки (radio) – похожи на чекбоксы, но имя поля передаётся без квадратных скобок, поэтому может быть выбран только один вариант. Число товаров также отображается.

2.3 Живые счётчики (фасетный подсчёт)

Главная особенность плагина — динамические числа напротив каждой опции. Когда посетитель отмечает фильтр по одному параметру и нажимает «Применить», страница перезагружается, и в форме все счётчики обновляются с учётом выбранного значения.

Пример: в категории «Электросамокаты» есть параметры «Вольтаж аккумулятора» (checkbox) и «Ёмкость аккумулятора» (select). При первом открытии страницы напротив «48V» может стоять число 20 (общее количество товаров с таким вольтажом), а напротив «21 А·ч» – число 8. После выбора «48V» и нажатия кнопки «Применить фильтры» страница обновляется. Теперь счётчик «21 А·ч» изменится и покажет количество товаров, у которых одновременно и вольтаж 48V, и ёмкость 21 А·ч – например, 3. Аналогично пересчитаются числа для всех остальных параметров. Это позволяет покупателю на лету понимать, сужается ли выбор, и не тратить время на комбинации, дающие нулевой результат.

Технически обновление происходит благодаря вызову marketprofilter_get_faceted_counts() для каждого параметра при построении формы. Функция анализирует все filter_* в $_GET, исключая тот, для которого вычисляются количества, и строит SQL с множественными INNER JOIN. Для учёта выбора внутри текущей группы (например, когда отмечены сразу несколько чекбоксов одной характеристики) используется EXISTS, что даёт корректные цифры внутри одной группы.

2.4 URL фильтра и пагинация

Все выбранные фильтры сохраняются в URL в виде параметров filter_<код_параметра>=<значение>. Плагин явно добавляет эти параметры в массив $list_url_path, который используется системой пагинации Cotonti. Благодаря этому ссылки на следующие страницы списка товаров автоматически содержат текущие фильтры, и пользователь может листать страницы, не теряя выбранные условия.

Кнопка «Сбросить фильтры» ведёт на чистый URL категории (cot_url('market', ['c' => $current_cat])), удаляя все filter_*.

2.5 Информационное сообщение

Над списком товаров (или в другом месте, определяемом шаблоном) отображается сообщение о количестве найденных позиций. Для этого используются переменные шаблона MARKETFILTER_MESSAGE и MARKETFILTER_MESSAGE_CLASS. Количество подставляется в строку локализации marketprofilter_found_items (например, «Найдено 5 позиций») или marketprofilter_no_items («Товаров по заданным параметрам не найдено»). Класс alert-success или alert-warning позволяет стилизовать сообщение соответствующим образом.

2.6 Представление параметров в карточке товара

На странице отдельного товара через тег {MARKET_FILTER_PARAMS} выводится таблица (или список) с присвоенными параметрами. Для каждого параметра показывается:

• Переведённое название параметра (PARAM_TITLE).
• Отформатированное значение (PARAM_VALUE): для диапазонов – «1000 — 1500», для чекбоксов – значения через запятую, для селектов и радио – текст опции.
• Подсказка (PARAM_HELP), если задана.

Шаблон этого блока находится в файле marketprofilter.market.tags.php.

2.7 Пример реального сценария использования

Покупатель заходит в категорию «Электросамокаты». Он видит фильтр с параметрами: бренд, мощность, вольтаж, ёмкость, диаметр колёс, тип амортизации, особенности. Все счётчики показывают общие количества. Он выбирает бренд «Kugoo» (число товаров уменьшается). Затем добавляет мощность «1700 – 2000 Вт». Счётчики для диаметра колёс, вольтажа и других характеристик обновляются, отражая только самокаты Kugoo с указанной мощностью. Покупатель решает посмотреть, сколько среди них моделей с колёсами 10 дюймов – видит цифру 4. Переходит по ссылке, листает результаты, не теряя фильтры.

Раздел 3. Руководство администратора

3.1 Доступ к управлению параметрами

Для настройки фильтра перейдите в панель администратора Cotonti, затем в раздел «Расширения» → «Market PRO Filter». Если плагин установлен корректно, вы увидите страницу с заголовком «Управление параметрами фильтрации».

3.2 Таблица существующих параметров

В нижней части страницы находится таблица со списком всех созданных параметров. Она имеет следующие колонки:

• ID – внутренний идентификатор.
• Код параметра – системное имя (например, 001_04_samokat_battery_voltage).
• Название параметра – переведённый заголовок (если перевода нет, показывается системный код).
• Тип параметра – одно из значений: range, select, checkbox, radio.
• Значения параметра (JSON) – содержимое поля param_values, выводится моноширинным шрифтом.
• Категория – код категории, к которой привязан параметр, или прочерк, если категория не задана.
• Активен – «Yes» или «No».
• 🔒 Админ – отметка, если параметр только для администраторов.
• Подсказка – первые 50 символов подсказки.
• Действия – кнопки «Edit» и «Delete».

Таблица поддерживает постраничную навигацию (пагинацию): если параметров больше 15 (значение из настроек Cotonti maxrowsperpage), появляются ссылки для перехода по страницам.

3.3 Добавление нового параметра

1. Нажмите кнопку «Добавление параметра», расположенную над таблицей.
2. Заполните появившуюся форму:
   • Код параметра (param_name) – уникальный идентификатор, латиница, цифры, подчёркивания, без пробелов. Пример: 001_samokat_max_speed. Этот код будет использоваться в URL (после filter_) и в базе данных. Изменение кода после создания нежелательно, так как это затронет уже существующие товары.
   • Название параметра (param_title) – служебное название на языке по умолчанию. Оно может быть переопределено в секции переводов для каждого языка.
   • Тип параметра (param_type) – выберите из выпадающего списка: «Диапазон», «Выпадающий список», «Чекбоксы», «Радиокнопки». От этого зависит, как будет выглядеть элемент в форме и как интерпретироваться значения.
   • Значения параметра (JSON) (param_values) – отредактируйте текстовое поле:
     • Для диапазона введите JSON-объект строго в формате {"min":0,"max":100}. min и max должны быть числами, причём min <= max.
     • Для списка/чекбоксов/радиокнопок введите JSON-массив строк, например ["val1","val2","val3"]. Каждая строка — это машинный ключ опции. В дальнейшем эти ключи будут переведены.
   • Категория (param_category) – выберите категорию Market, к которой будет относиться параметр. Если оставить пустым, параметр будет отображаться во всех категориях (общий параметр). Например, можно указать electric-scooters.
   • Активен (param_active) – отметьте галочку, чтобы параметр сразу отображался в фильтре.
   • Только для администраторов (param_superadmin) – если отметить, параметр будет скрыт от обычных посетителей и доступен только для пользователей группы администраторов (группа 5). Это удобно для служебных характеристик, которые не должны влиять на публичную фильтрацию.
   • Подсказка / Пояснение (param_helpinfo) – необязательное поле. Здесь можно ввести текст (допускается HTML), который будет показываться в виде всплывающей подсказки рядом с параметром в форме фильтра и в карточке товара.
3. Нажмите «Добавить» (Add).

3.4 Редактирование параметра

1. В таблице параметров нажмите кнопку «Edit» напротив нужной записи.
2. Вы перейдёте на форму редактирования, которая аналогична форме добавления, но уже заполнена текущими данными.
3. Внесите необходимые изменения и нажмите «Сохранить» (Save). Для отмены изменений нажмите «Отмена» (Cancel), которая вернёт вас к списку параметров.

Важно: поле «Код параметра» не следует изменять без крайней необходимости, так как оно используется как ключ во многих местах.

3.5 Удаление параметра

Нажмите кнопку «Delete» в строке параметра. Появится подтверждение удаления. После подтверждения параметр, все его переводы и связи с товарами будут удалены без возможности восстановления.

3.6 Переводы (мультиязычность)

При редактировании параметра под основной формой находится секция «Переводы». Для каждого поддерживаемого языка (RU, EN, UA) предлагаются три поля:

• Название параметра (XX) – переведённый заголовок, который увидят пользователи с соответствующим языком интерфейса.
• Перевод значений (XX) – здесь нужно ввести JSON-объект, где ключи строго соответствуют значениям из param_values, а значения – это их перевод. Например, если param_values = ["red","green"], то i18n_values для русского языка должен быть {"red":"Красный","green":"Зелёный"}. Для типа range это поле не отображается.
• Подсказка / Пояснение (XX) – перевод текста подсказки.

Если какое-либо поле оставить пустым, будет использоваться значение на языке по умолчанию или технический ключ.

3.7 Управление кешем

Кеш фасетных подсчётов обновляется автоматически при сохранении товара. Если по какой-либо причине требуется полностью очистить кеш, достаточно удалить все файлы с расширением .cache в папке datas/cache/marketprofilter/ (например, через FTP или файловый менеджер). Другой вариант – временно закомментировать строчку очистки в хуке сохранения товара, но в штатной работе это не требуется.

3.8 Логирование

Плагин имеет встроенную систему логирования, которая записывает отладочную информацию в файлы внутри папки plugins/marketprofilter/logs/. Чтобы включить запись логов, необходимо в настройках плагина (Конфигурация → Market PRO Filter) установить параметр «Включить ведение журнала и логирование» в значение «Да». Логи сохраняются в файл marketprofilter.log, а каждые 72 часа архивная копия создаётся с меткой времени. Это помогает диагностировать проблемы с фильтрацией.

3.9 Примеры JSON для различных типов

При заполнении поля «Значения параметра (JSON)» важно соблюдать синтаксис:

• Диапазон мощности (Вт):

  json

  {"min":0,"max":3000}

• Выпадающий список диаметров колёс (дюймы):

  json

  ["8","10","12","14","16","20"]

• Чекбоксы особенностей модификации:

  json

  ["digital_display","speedometer","mobile_app","foldable","seat","suspension"]

• Радиокнопки типа амортизации:

  json

  ["no_suspension","front_suspension","rear_suspension","dual_suspension"]

Используйте двойные кавычки для ключей и строковых значений. После последнего элемента запятую ставить нельзя. Проверить валидность JSON можно с помощью любого онлайн-валидатора (например, jsonlint.com). Некорректный JSON вызовет ошибку при сохранении параметра.

3.10 Рекомендации по организации параметров

• Группируйте параметры по смыслу. Коды параметров удобно именовать с префиксом категории или тематики, например 001_ для электросамокатов, 002_ для электровелосипедов.
• Не злоупотребляйте чекбоксами с большим количеством опций – каждая опция порождает отдельную запись в таблице значений, что может замедлить работу при очень большом количестве товаров (тысячи и десятки тысяч). Впрочем, для типичных интернет-магазинов это не является проблемой.
• Используйте суперадминские параметры для скрытых технических данных (например, имена поставщиков, внутренние артикулы), которые не должны быть видны покупателям.
• Регулярно проверяйте логи, особенно после обновлений плагина или изменений в структуре категорий.

Заключение

Плагин Market PRO Filter представляет собой мощный, гибкий и глубоко проработанный инструмент фильтрации товаров для Cotonti. Сочетание фасетной логики, продуманной индексации, файлового кеширования и полной поддержки мультиязычности делает его подходящим как для небольших каталогов, так и для крупных магазинов с сотнями характеристик. Детальная документация, представленная выше, поможет и разработчикам, и администраторам эффективно использовать все возможности плагина, а покупателям — быстро находить нужные товары в удобном интерфейсе.