Поиск FacetWP в WordPress: настройка, ошибки и как их исправлять — подробная инструкция

Кому нужна эта инструкция

Это практическое руководство по поиску FacetWP: как правильно поставить плагин, настроить поисковый фасет, связать его с листингом, проверить работу и — самое главное — что делать, когда поиск «не ищет», отдаёт 502 или роняет весь сайт. Все шаги проверены на живом проекте с каталогом курсов (Tutor LMS, ~160 записей, фильтры сверху, мобильная панель фильтров).

Правило номер один: FacetWP работает «из коробки», если не мешать ему кастомными сниппетами и не трогать его настройки в базе руками. 90% проблем, описанных ниже, — это следствие вмешательства.

1. Как устроен FacetWP (обязательно к прочтению)

FacetWP не заменяет поиск WordPress. Он строит собственную таблицу индекса (wp_facetwp_index), где для каждой записи и каждого фасета хранится значение. Поиск и фильтры работают по этому индексу, а не по живым запросам к постам.

• Listing / Template — что выводим (тип записей, сортировка, количество на страницу, разметка карточки).
• Facet — чем фильтруем (поиск, чекбоксы, категории, метки, пагинация).
• Index — таблица, из которой берутся значения фасетов.
• Settings — вся конфигурация лежит в одной опции facetwp_settings в таблице wp_options в виде JSON-строки.

Отсюда два железных вывода: после любых изменений типов записей, таксономий или полей нужна переиндексация; а опцию facetwp_settings нельзя записывать ничем, кроме админки плагина или прямого UPDATE корректной JSON-строки.

2. Установка и первичная настройка

1. Установите плагин FacetWP и активируйте лицензию (Settings → FacetWP → Settings → License). Без валидной лицензии обновления и часть аддонов (например, Mobile Flyout) недоступны.
2. Создайте листинг: FacetWP → Listings → Add New. Выберите тип записей, количество на страницу, сортировку. Разметку карточки собирайте в визуальном Listing Builder — не в коде.
3. Создайте фасеты: FacetWP → Facets.
4. Запустите индексацию: FacetWP → Settings → Indexer → Re-index.
5. Вставьте шорткоды на страницу каталога.

Важно: шорткод на странице обязателен. Без него фасеты «висят» и ничего не фильтруют.

3. Настройка поискового фасета правильно

Тип фасета — Search. Ключевые параметры:

• Search engine: WP Default — ищет по заголовку, отрывку (excerpt) и содержимому записи. Если подключён SearchWP или Relevanssi, выбирайте его — тогда поиск умеет морфологию и синонимы.
• Enable relevance (relevancy sorting): Yes — результаты сортируются по релевантности, а не по дате.
• Auto refresh: Yes — результаты обновляются при вводе (с задержкой). Если у вас тяжёлый каталог, ставьте No и оставьте кнопку «Найти».
• Placeholder — человеческий текст вроде «Поиск по курсам».

Поиск не индексируется в wp_facetwp_index как значения — он работает через поисковый запрос WP по выборке листинга. Поэтому «пустой результат» почти всегда означает: либо слово реально отсутствует в заголовке/отрывке/тексте, либо листинг ограничен не тем типом записей, либо в запрос вмешался сторонний код.

Почему поиск «не находит очевидное»

• Нет морфологии. WP Default ищет подстроку. «Анализ» найдёт «анализа», но «психолог» не найдёт «психологический» не всегда предсказуемо. Решение — SearchWP/Relevanssi как движок поиска в фасете.
• Пустые отрывки. Если у записей нет excerpt и описание лежит в мета-полях или в конструкторе страниц, WP их не видит. Заполните описания или подключите движок, который индексирует мета.
• Контент внутри шорткодов / блоков page builder. Такой текст в post_content часто хранится в служебном виде — поиск по нему даёт мусор или ноль.
• Черновики и приватные записи. Они не индексируются. Проверяйте статус.

4. Индексация: когда и как

Переиндексация обязательна после: добавления/изменения фасета, смены таксономий, массового импорта записей, восстановления настроек из резервной копии, смены типа записей у листинга.

Через админку: FacetWP → Settings → Indexer → Re-index. Через WP-CLI:

wp facetwp index
wp facetwp index --post_id=123

Если индексация «висит» на одном проценте — почти всегда виноват тяжёлый хук facetwp_index_row в чужом сниппете или таймаут PHP. Поднимите max_execution_time, индексируйте порциями по post_id.

5. Мобильные фильтры

Штатное решение — аддон Mobile Flyout (требует активной лицензии). Он даёт кнопку «Фильтры», выезжающую панель и штатный сброс. Пока лицензии нет, допустима простая обёртка: кнопка, открывающая контейнер с фасетами, плюс ссылка сброса на ?_reset. Не пытайтесь дублировать фасеты в двух местах на одной странице — FacetWP работает с одним экземпляром фасета, второй ломает синхронизацию состояния.

6. Кэш — вторая по частоте причина «фильтры не работают»

AJAX-ответы FacetWP кэшировать нельзя. Настройте исключения:

• исключить из кэша страниц URL с параметрами _* (например _course_search, _paged);
• исключить admin-ajax.php и /wp-json/facetwp/*;
• не минифицировать/не объединять скрипты FacetWP в агрессивном режиме — ломается инициализация;
• после любых правок контента и настроек — сброс кэша (включая объектный кэш Redis: redis-cli FLUSHALL или wp cache flush).

Типичный симптом: первый заход фильтрует корректно, повторный отдаёт старую выдачу или «замерзает» на прелоадере — это кэш.

7. Каталог ошибок и как их лечить

7.1 Белый экран / ошибка 500 сразу после активации FacetWP

Причина в 99% случаев: опция facetwp_settings испорчена. Плагин ожидает JSON-строку, а в базе лежит сериализованный PHP-массив (a:0:{}) или пустое значение. В логах видно TypeError: json_decode(): Argument #1 ($json) must be of type string, array given в class-helper.php.

Лечение:

1. Срочно поднять сайт: переименовать папку плагина (wp-content/plugins/facetwp → facetwp_off) по SSH/FTP.
2. Взять резервную копию конфигурации из опции facetwp_settings_last_index — там лежит рабочий JSON.
3. Записать её обратно как строку, прямым SQL:

UPDATE wp_options
SET option_value = '<валидный JSON>'
WHERE option_name = 'facetwp_settings';

4. Сбросить кэш, вернуть имя папки плагина, переиндексировать, проверить каталог.

Никогда не записывайте эту опцию через update_option() с массивом, через «универсальные» REST-эндпоинты или плагины редактирования опций, которые «санитизируют» значение — они превратят JSON в a:0:{} и сайт снова упадёт.

7.2 Ошибка 502 при поиске по некоторым словам

Сайт открывается, обычный поиск WP работает, а AJAX FacetWP по отдельным словам даёт 502. Что проверять по порядку:

• Неполная конфигурация листинга. Если в настройках листинга отсутствуют обязательные поля (источник изображения, поле сортировки), PHP на каждой карточке пишет warning. На выдаче из сотен карточек ответ раздувается предупреждениями, и nginx обрывает его как 502. Лечение — дозаполнить листинг в Listing Builder штатно.
• Таймаут PHP-FPM / nginx. Смотрите /var/log/nginx/error.log: upstream prematurely closed connection или recv() failed. Поднимайте fastcgi_read_timeout, request_terminate_timeout, число воркеров pm.max_children.
• Тяжёлый сторонний запрос. Сниппеты на facetwp_query_args с подзапросами и meta_query по неиндексированным полям могут дать многосекундный SQL.

Диагностика одной строкой:

tail -n 200 /var/log/nginx/error.log
tail -n 200 wp-content/debug.log

7.3 Фасеты «слетают»: фильтры показываются как текст или не реагируют

Скрипты и стили FacetWP подключаются только там, где плагин увидел свой шорткод. Если каталог выводится нестандартно (шорткод внутри блока, в шаблоне темы, в виджете), ассеты не подключаются. Штатное решение — фильтр facetwp_load_assets (вернуть true на нужных страницах). Проверка: в исходном коде страницы должен быть facetwp-front.js, а в консоли доступен объект FWP.

7.4 Поиск работает для гостя и ломается под логином (или наоборот)

Причина — кэш для авторизованных, либо nonce. AJAX-запросы FacetWP должны уходить с корректным X-WP-Nonce; при агрессивном кэше HTML nonce устаревает, и ответ приходит от имени гостя — карточки меняют вид (например, вместо кнопки «Начать обучение» показывается цена). Лечение: не кэшировать HTML для авторизованных, исключить AJAX из кэша.

7.5 Дубли фасетов

Два поисковых фасета с похожими именами (например course_search и coursesearchcode) — классика после экспериментов и импортов. Лишний фасет остаётся в настройках, ломает состояние и создаёт непредсказуемые результаты. Удаляйте дубли в FacetWP → Facets и переиндексируйте.

7.6 Пагинация не работает / вторая страница пустая

Проверьте: фасет типа Pager добавлен и вставлен шорткодом; в листинге задано posts per page; сторонний сниппет не перетирает paged в facetwp_query_args.

7.7 Сортировка «съедает» поиск

Если свой сниппет принудительно задаёт orderby в facetwp_query_args, он перебивает сортировку по релевантности — поиск «находит не то». Либо отключите сниппет, либо не трогайте orderby, когда в запросе присутствует поисковая строка.

7.8 На странице выводится слово «Array» или мусор

Признак того, что где-то в опции/мета лежит массив вместо строки (часто последствие неудачного восстановления настроек). Ищите источник и записывайте корректный тип значения.

8. Чек-лист диагностики (сверху вниз)

1. Сайт вообще отвечает 200? Если 500 — сразу подозревайте facetwp_settings.
2. В /var/log/nginx/error.log и debug.log есть свежие записи по времени сбоя?
3. На странице есть шорткод ?
4. Скрипты FacetWP подключены, в консоли есть объект FWP?
5. Индекс не пустой: SELECT COUNT(*) FROM wp_facetwp_index;
6. Слово реально встречается в заголовке/отрывке/тексте опубликованных записей?
7. Кэш сброшен, AJAX и URL с _-параметрами исключены из кэша?
8. Отключите все сторонние сниппеты, трогающие facetwp_query_args / facetwp_index_row, и проверьте снова.
9. Только после этого меняйте настройки фасета.

9. Полезные команды

# индекс
wp facetwp index
# сколько строк в индексе
wp db query "SELECT COUNT(*) FROM wp_facetwp_index;"
# резервная копия настроек перед любыми правками
wp db query "SELECT option_value FROM wp_options WHERE option_name='facetwp_settings';" > fwp-backup.json
# сброс кэша
wp cache flush
redis-cli FLUSHALL

10. Правила эксплуатации для команды

• Любые изменения фасетов и листингов — только через админку FacetWP.
• Перед правками — бэкап опции facetwp_settings в файл.
• Никаких CSS- и PHP-«заплаток» там, где есть штатная настройка: колонки, отступы, сортировка, пагинация настраиваются в Listing Builder.
• После правок — переиндексация и сброс кэша.
• После восстановления настроек из бэкапа обязательно откройте каталог, поиск по 3–4 словам и мобильную панель фильтров.
• Держите в проекте не более одного поискового фасета на каталог.

Итог

FacetWP надёжен при одном условии: его конфигурация живёт в его собственной админке, индекс регулярно пересобирается, а AJAX не кэшируется. Практически все «неработающие поиски» и падения сайта сводятся к испорченной опции facetwp_settings, неполному листингу, кэшу или чужому коду в хуках запроса. Пройдите чек-лист из раздела 8 — и поиск будет работать предсказуемо.