Hooks and filters

Introduction

WPXFacets offers three kinds of extension points:

• Filters change a value WPXFacets is about to use and return it, such as the labels of facet values.
• Actions tell your code that something happened. The listing action xfacets_after_product_search is observational: changing its argument changes nothing.
• Browser events let theme and plugin scripts react to searches in the page, such as xfacets:results-updated.

Put PHP in a small site plugin or a must-use plugin (wp-content/mu-plugins), not in a theme you may replace. Hooks that change indexed data take effect when products are next synced.

Each entry lists which search engine it applies to. Managed search is the WPXFacets search service; the WordPress fallback serves listings from the WordPress database when managed search is off, unavailable or fails. A hook marked for one engine does not run on the other.

Product cards in WPXFacets results come from WooCommerce’s own content-product template, on page load and after each refinement, so WooCommerce’s product-loop hooks keep working on them. Those are WooCommerce hooks, not WPXFacets contracts.

Recipes

Rename facet values

Raw meta values such as yes and no make poor labels. xfacets_facet_values lets you replace the label of a value; counts, selections and swatches stay as the search engine returned them, and a value the shopper selected always stays visible.

add_filter(
	'xfacets_facet_values',
	function ( array $values, array $facet ) {
		// Only the facet that reads the `gift_wrap` meta field.
		if ( 'meta_field' !== $facet['source'] || 'gift_wrap' !== $facet['source_value'] ) {
			return $values;
		}

		// Fixed English labels. A translated callback must use the third argument's
		// `language` or `locale`, not the current WordPress locale.
		$labels = array(
			'yes' => 'Gift wrap available',
			'no'  => 'No gift wrap',
		);

		foreach ( $values as $index => $row ) {
			if ( isset( $labels[ (string) $row['slug'] ] ) ) {
				$values[ $index ]['label'] = $labels[ (string) $row['slug'] ];
			}
		}

		return $values;
	},
	10,
	2
);

This example supplies fixed English labels. To translate labels, use the language or locale of the third argument, $context: in a REST refinement the values are built before WordPress switches to the catalogue locale, so the current locale can be the wrong one. The same filter can reorder values or remove unselected ones, on page load and after every refinement, on both search engines.

Keep a meta key out of the managed index

Public product meta is indexed for managed search. xfacets_excluded_meta_keys removes an exact key, in addition to the built-in denylist for sensitive names.

add_filter(
	'xfacets_excluded_meta_keys',
	function ( array $keys ) {
		$keys[] = 'supplier_cost';

		return $keys;
	}
);

Products keep the old value in the index until they are synced again: run a full sync after adding the filter. The WordPress fallback reads the database and is not affected.

Adjust the Search Bar

xfacets_search_bar_runtime_config changes Search Bar options in code, including ones without a setting such as recent searches. WPXFacets clamps every value afterwards, so out-of-range numbers are corrected.

add_filter(
	'xfacets_search_bar_runtime_config',
	function ( array $config ) {
		$config['show_recent']      = false;
		$config['completion_limit'] = 8;

		return $config;
	}
);

Update a custom product counter

Listen for xfacets:results-updated on document. It fires once per results container, so deduplicate on detail.requestId when the effect belongs to the whole listing. Zero matches are a normal update with detail.count 0.

let lastRequestId = null;

document.addEventListener( 'xfacets:results-updated', ( event ) => {
	// One event arrives per results container; act once per listing.
	if ( event.detail.requestId === lastRequestId ) {
		return;
	}
	lastRequestId = event.detail.requestId;

	const counter = document.querySelector( '.my-product-counter' );
	if ( counter ) {
		counter.textContent = 0 === event.detail.count
			? 'No products match'
			: event.detail.count + ' products';
	}
} );

Failed searches send xfacets:search-failed instead and leave the previous results in place.

PHP hooks (21)

Supported PHP hooks for integrations, in alphabetical order.

xfacets_after_product_search

Fires after a storefront product listing was resolved and its facets hydrated.

Observational. Fires once per successful listing query of the Shop page, the results shortcode or block (page) and every REST refinement (rest), on managed search and on the WordPress fallback, after facet values and the best-effort Search Analytics step; zero matches still fire. It does not fire when both engines failed, nor for the facet-order visibility probe, Trending verification or autosuggest. Engine, fallback reason and language are recorded when the query ran, before xfacets_after_page_facets_query listeners. The argument is a copy: changing it changes nothing. It carries no search text, selections, product IDs, URL or internal identifiers. PHP does not run on page or edge cache hits, so this is not a page-view count. Callbacks run inside the storefront request: defer slow external calls.

Arguments

1. $search (array): Listing summary.
   • $contract (int): 1.
   • $surface (string): page or rest.
   • $engine (string): managed or wordpress.
   • $fallback_reason (string): none, filter_mode, force_wp, http_error, transport_error or payload_error.
   • $count (int): Matching products, at least 0.
   • $count_relation (string): eq (exact), gte (lower bound) or unknown.
   • $page (int): 1-based page.
   • $per_page (int): Page size; -1 when the caller asked for every product.
   • $sort (string): Effective <order_by>-<order>, for example price-asc.
   • $language (string): Canonical catalogue language the engine searched with, ” when it had none.
   • $search_active (bool): Whether a keyword (Search Bar or Search facet) applied.

xfacets_allowed_meta_keys

Filters the protected (underscore-prefixed) meta keys that may be indexed.

Protected meta is skipped unless its exact key is listed here; the sensitive-key denylist and xfacets_excluded_meta_keys still win. The same list decides whether a change to a protected key queues the product for incremental sync and whether the key may back a swatch mapping. The plugin’s WooCommerce integration adds its own keys through this filter. Changes take effect on each product’s next sync.

Arguments

1. $allowed_meta_keys (string[]): Allowed protected keys. Default array( '_thumbnail_id' ).
2. $indexable (\XFacets\Indexables\XFacets_Product_Indexable): Current indexable.

Returns string[]: Allowed protected keys.

xfacets_defer_sync_on_save

Filters whether sync-on-save is suspended for the current request.

Read at every queueing and flush entry point, so a script can toggle it partway through a request. The XFACETS_DISABLE_SYNC constant, when true, wins before the filter runs. The result is cast to bool.

Arguments

1. $deferred (bool): Whether to skip queueing and flushing. Default false.

Returns bool: Whether sync-on-save is suspended.

xfacets_excluded_meta_keys

Filters the exact meta keys that are never indexed.

Checked for every meta key after the built-in sensitive substring denylist (password, token, _billing_ and similar), which always applies. The same check decides whether a meta key may back a swatch mapping. Changes take effect on each product’s next sync.

Arguments

1. $keys (string[]): Exact meta keys to exclude. Default empty.

Returns string[]: Exact meta keys to exclude.

xfacets_facet_usage_events_rate_limit

Filters the per-visitor request budget of one public REST route.

The hook name is fixed by the route’s controller when it constructs this guard. Read once per request, when the route spends the caller’s budget. The result is cast to an array and clamped: limit 1–600 requests per window of 10–300 seconds; a missing key keeps the route default.

This name: Facet usage events route. Default 30 requests per 60 seconds.

Arguments

1. $policy (array): Route defaults: limit and window in seconds.
2. $request (mixed): Current REST request.

Returns array: Policy.

xfacets_facet_usage_server_consent

Filters whether this request’s visitor may be counted by category facet usage.

Read by the public facet usage events endpoint for each submitted batch. Return false to refuse a visitor your consent tool has not cleared; the browser then ends its session. Only a refusal is effective: the filter does not run when the WP Consent API already refused, and any value other than false keeps the incoming answer.

Arguments

1. $consent (bool): The WP Consent API’s statistics answer, or true when it is absent.

Returns bool: False to refuse.

xfacets_facet_values

Filters the value rows of one refinement-list facet before they reach the storefront.

Runs once per refinement-list facet (checkbox, radio and rating displays) of every storefront listing query: the Shop page, the results shortcode or block and every REST refinement, on managed search and on the WordPress fallback, after rows were built and swatches were added. Range and Search facets, the facet-order visibility probe, Trending verification and autosuggest never run it. Rows are matched back to the originals by slug: only a valid label (a string, plain text after tags are stripped, at most 200 characters) is taken from a callback, and unknown, duplicate or malformed rows are dropped. Selected or excluded rows the callback removed are appended again in their original order. A non-array return keeps the original rows and warns once per request. Exceptions are not caught. Keep callbacks deterministic for their arguments and do not personalize them. Refinements are public GET requests, but that does not make their responses safe to cache by URL: the product HTML they carry depends on the shopper’s tax and currency context. $context['language'] and $context['locale'] are the ones the engine executed the listing with; in a REST refinement rows are built before the product HTML switches to that locale, so translate with them, not the current locale.

Arguments

1. $original (array): Ordered list of value rows.
   • Each item (array):
     • $slug (int|string): Value identity; numeric values may be integers.
     • $label (mixed): Display label.
     • $count (int|string): Matching products, as the engine returned it.
     • $swatch (array): Optional swatch (type color or image).
2. $facet (array): Read-only description of the facet.
   • $id (int): Facet ID.
   • $form_id (int): Filter form ID.
   • $slug (string): Facet slug (the URL parameter after the prefix).
   • $type (string): Behavioral type, always refinement_list here.
   • $display_type (string): checkbox, radio or rating.
   • $source (string): Value source, for example product_attribute or meta_field.
   • $source_value (string): Source field, for example pa_color or a meta key.
3. $context (array): Listing context.
   • $contract (int): 1.
   • $surface (string): page or rest.
   • $engine (string): managed or wordpress.
   • $language (string): Canonical catalogue language the engine searched with, ” when it had none.
   • $locale (string): Catalogue locale of that language, ” when unavailable.
   • $search_active (bool): Whether a keyword (Search Bar or Search facet) applied.

Returns array: Ordered list of value rows.

xfacets_search_analytics_budget_policy

Filters the Search Analytics write budget.

Read each time a search event is about to be recorded. The result is clamped: caller_limit 1–300 per caller_window of 10–300 seconds, and daily_write_limit 100–1,000,000.

Arguments

1. $policy (array): caller_limit 30, caller_window 60 and daily_write_limit 50000.

Returns array: Policy.

xfacets_search_analytics_should_record

Filters whether an otherwise eligible search is recorded by Search Analytics.

Runs after every built-in eligibility check passed, on a first-paint storefront search. It deliberately receives no search terms. Only an exact true allows recording.

Arguments

1. $allowed (bool): Whether to record. Default true.

Returns bool: Exactly true to record.

xfacets_search_bar_results_url

Filters the URL the Search Bar form submits to.

Runs when the Search Bar renders (shortcode, block or editor preview). The default is the current-language Search results page, else the WooCommerce Shop page. The result is cast to a string and passed through esc_url_raw(); an empty URL renders a configuration message for editors and nothing for visitors.

Arguments

1. $url (string): Results URL.
2. $status (array): Results page status (configured, valid, page_id, url, fallback, warning, …).

Returns string: Results URL.

xfacets_search_bar_runtime_config

Filters the runtime Search Bar configuration.

Read when the Search Bar renders and by the autosuggest endpoint. Every key is sanitized and clamped after the filter: minimum_characters 1–10, completion_limit 1–12, product_limit 1–10, featured_limit 0–8, query_ttl 5–300 and zero_ttl 30–3600 seconds. The plugin’s Polylang integration consumes this filter.

Arguments

1. $config (array): Configuration: stored settings plus featured_limit 4, show_correction and show_recent true, query_ttl 30 and zero_ttl 300.

Returns array: Configuration.

xfacets_search_fields

Filters the weighted Text paths of one search input in managed queries.

Runs when the managed query builder handles the Search Bar keyword or one Search facet. Exact and Prefix fields are not part of this list and cannot be added through it. An empty or non-array return keeps the original paths. The WordPress fallback uses xfacets_wp_search_fields instead.

Arguments

1. $paths (string[]): path^weight expressions for the input’s Text fields.
2. $facet (\XFacets\Models\Facets\XFacets_Facet|null): The Search facet, or null for the Search Bar.
3. $context (array): surface (search_bar or facet) and canonical fields.

Returns string[]: path^weight expressions.

xfacets_search_products_circuit_breaker

Filters the backend circuit-breaker policy of one public REST route.

The hook name is fixed by the route’s controller when it constructs this guard. Read whenever the route evaluates its circuit breaker: backend failures and slow responses. The result is cast to an array and clamped: failures 1–10, cooldown 5–300 seconds, slow_seconds 0.1–10; a missing key keeps the route default.

This name: Product refinement route. Defaults: 3 failures, 30 s cooldown, 2.5 s slow threshold.

Arguments

1. $policy (array): Route defaults: failures, cooldown and slow_seconds.

Returns array: Policy.

xfacets_search_products_rate_limit

Filters the per-visitor request budget of one public REST route.

The hook name is fixed by the route’s controller when it constructs this guard. Read once per request, when the route spends the caller’s budget. The result is cast to an array and clamped: limit 1–600 requests per window of 10–300 seconds; a missing key keeps the route default.

This name: Product refinement route. Default 90 requests per 60 seconds.

Arguments

1. $policy (array): Route defaults: limit and window in seconds.
2. $request (mixed): Current REST request.

Returns array: Policy.

xfacets_search_suggest_circuit_breaker

Filters the backend circuit-breaker policy of one public REST route.

The hook name is fixed by the route’s controller when it constructs this guard. Read whenever the route evaluates its circuit breaker: backend failures and slow responses. The result is cast to an array and clamped: failures 1–10, cooldown 5–300 seconds, slow_seconds 0.1–10; a missing key keeps the route default.

This name: Autosuggest route. Defaults: 3 failures, 30 s cooldown, 1.5 s slow threshold.

Arguments

1. $policy (array): Route defaults: failures, cooldown and slow_seconds.

Returns array: Policy.

xfacets_search_suggest_rate_limit

Filters the per-visitor request budget of one public REST route.

The hook name is fixed by the route’s controller when it constructs this guard. Read once per request, when the route spends the caller’s budget. The result is cast to an array and clamped: limit 1–600 requests per window of 10–300 seconds; a missing key keeps the route default.

This name: Autosuggest route. Default 120 requests per 60 seconds.

Arguments

1. $policy (array): Route defaults: limit and window in seconds.
2. $request (mixed): Current REST request.

Returns array: Policy.

xfacets_sync_batch_size

Filters the batch size of one full-sync session.

Read once when a session starts, so a driver can override the stored setting for one run (wp xfacets index rebuild --batch-size=50 on a memory-starved host) without writing to xfacets_settings. The result is cast to int with a minimum of 1. The product transport still splits each batch into smaller gateway write requests.

Arguments

1. $limit (int): Items per batch. Default: the stored setting, else 300.
2. $driver (string): Driver starting the session: ajax or cli.

Returns int: Items per batch.

xfacets_sync_taxonomies

Filters the taxonomies whose terms are indexed with one product.

Runs per product during document preparation. The default is every public or publicly queryable taxonomy of the post type. After the filter, names are converted to taxonomy objects and unknown taxonomies are dropped. The plugin’s WooCommerce integration consumes this filter. Takes effect on the product’s next sync.

Arguments

1. $selected_taxonomies (array<\WP_Taxonomy|string>): Taxonomy objects or names.
2. $post (\WP_Post): Product post.

Returns array<\WP_Taxonomy|string>: Taxonomy objects or names.

xfacets_term_fanout_limit

Filters how many products a single term edit may queue for incremental sync.

Read when a term is edited, after counting its products. Above the limit the inline work is declined and the index is marked stale for a full reindex. The result is cast to int; zero or less disables the cap.

Arguments

1. $limit (int): Maximum affected products processed inline. Default 5000.
2. $taxonomy (string): Taxonomy of the edited term.

Returns int: Maximum affected products.

xfacets_url_facet_prefix

Filters the URL query-variable prefix of facet, page and sort parameters.

Read on every request that builds or reads facet URLs, in PHP and, through xfacets_search_data.facets_prefix, in the browser. Facet objects read it once, when they are constructed. The value is not validated: an empty prefix makes facet slugs collide with WordPress query variables such as page, paged and s.

Arguments

1. $prefix (string): Prefix. Default f_.

Returns string: Prefix.

xfacets_wp_search_fields

Filters the WordPress fallback descriptors of one search input.

Runs when the WordPress fallback builds the keyword clause of the Search Bar query or of one Search facet. An empty or non-array return keeps the original descriptors; descriptor types and modes are validated again when the SQL is built, and unknown types are skipped. The managed engine uses xfacets_search_fields instead.

Arguments

1. $descriptors (array): post_field, meta or taxonomy descriptors with weight and match.
2. $context (array): surface (search_bar or facet), canonical fields and facet.

Returns array: Descriptors.

Browser events (6)

Native events from WPXFacets are CustomEvent objects dispatched on each .xfacets-search-results element. They bubble to document, cannot be cancelled, and carry a frozen detail object of plain values: detail.contract, detail.requestId, detail.source, then detail.count, detail.page, detail.perPage and detail.sort for an update, or detail.code and detail.retryAfter for a failure. An update fires after the product grid was replaced and the filters re-rendered, and once on page load with requestId 0. A response that a newer search replaced fires nothing. These values are what the browser requested; use xfacets_after_product_search for what the server executed. The older jQuery events still fire as before. Some entries are things your code provides — a wp.hooks filter or an event you dispatch — rather than notifications from WPXFacets; their kind says which.

xfacets-facets.facets-loaded

Fired on every .xfacets-search-facets element after a filter form app hydrated its facets from the first-paint data.

Limits

• Namespaced jQuery event with no arguments; addEventListener cannot receive it.
• Hydration runs once per filter form app, so a page with several forms fires it once per form on every element.

xfacets-facets.search-done

Fired on every .xfacets-search-results element when a product refinement request finished.

Limits

• Fires on failure as well as on success; there is no payload saying which, and none with count, page or sort.
• Fires after the grid HTML was replaced and before Vue re-renders the facets; a superseded response fires nothing.
• Namespaced jQuery event; addEventListener cannot receive it.

xfacets:results-updated

Fired on every .xfacets-search-results element after a successful search replaced the product grid HTML and Vue re-rendered the facets.

Fires for refinements, sorting, paging, Back/Forward and Clear all, including searches with zero matches. On page load it fires once, after the first Vue render, with source hydration and requestId 0 — unless the page needs a follow-up search to complete its facets, in which case that search’s update is the first event, or a newer search started first. A response superseded by a newer search fires nothing, also when it is superseded while Vue renders. Bubbles to document; not cancelable.

Limits

• Client request metadata: server-side changes made through xfacets_page_request are not reflected.
• One event per results container; deduplicate on requestId for once-per-listing effects.
• No search text, selections, URL, product or customer identifiers.

xfacets:search-failed

Fired on every .xfacets-search-results element when a current search failed, after the existing error message. The previous product grid stays in place and no xfacets:results-updated follows.

Also fires, with request_failed, when a successful response carried no usable results fragment, because the grid was not replaced. A failure superseded by a newer search fires nothing. Bubbles to document; not cancelable.

Limits

• No error text or response body.
• A response that cannot be read at all (no facets object) rejects the search before any event, as the legacy signal does not fire either.

xfacets_facet_usage_consent

Lets a consent integration refuse category facet usage collection for this visitor.

Limits

• Receives true; returning exactly false, or throwing, refuses. It cannot overrule a refusal of the WP Consent API.
• The facets script declares the core wp-hooks dependency, so wp.hooks is loaded before it wherever WordPress prints the script.

xfacets_facet_usage_consent_change

Dispatched on document by a site’s consent tool when the visitor changes the choice; collection then starts or stops according to the current consent state.

Limits

• Only signals a change; the state itself is read from window.xfacets_facet_usage_consent, the xfacets_facet_usage_consent filter and the WP Consent API.

Advanced PHP hooks (30)

These hooks work, but expose engine-specific structures, mutable internal objects or operator settings. Read each caveat; some change only one search engine, and some can break listings or indexing when misused. They are specialist extension points, without a promise that their signatures stay stable.

Not for integrations

The names below exist in the plugin but are not integration points. Do not build on them: they can change or disappear without notice. An inactive entry is not deprecated in any released version; it is simply not reached by current code.

Internal hooks and events

• xfacets_after_display_results: Fires after the first-paint product grid of a storefront listing has been produced.
• xfacets_analyzer_profile: Filters the analyzer profile chosen by the legacy site-wide resolver.
• xfacets_analyzer_profile_map: Filters the locale-to-analyzer-profile map.
• xfacets_search_bar_trending_result_warnings: Filters the Trending verification warnings before the live check runs.
• xfacets_site_serves_multiple_languages: Filters whether the site counts as multilingual for the legacy site-wide analyzer.
• xfs_api_base: Filters the control-plane API origin used for updates, licensing and managed slot calls.
• xkit-i18n: Filters the translated strings printed as window.xkit_i18n for the shared scripts.
• xkit-params: Filters the parameters printed as window.xkit_params for the shared scripts.
• xfacets-filter-drawer-open: Fired on document just before a filter drawer opens, so other drawers close.
• xfacets_initial_load_data_from_server: Hydration handshake: the page bootstrap triggers it on window once the first-paint facet data has been printed, and every filter form app hydrates from that data.

Inactive entries

• xfacets_facet_usage_events_circuit_breaker: Filters the backend circuit-breaker policy of one public REST route. Inactive: The facet usage events route only spends the request budget; it never records failures or timings, so this policy is never read.
• xfacets_synonyms_set_name: Filters the Elasticsearch synonym set name of the legacy plugin-built mapping. Inactive: Only the legacy mapping file calls get_set_name(), and that file is required only by XFacets_Product_Indexable::generate_mapping(), which has no production caller.
• xfacets-facets.mounted: Intended to fire after the facets app mounted, for result-area integrations. Dead: apps/Facets.vue triggers it on .xfacets-search-results-wrapper, which no rendered element carries, so no listener ever receives it.

WooCommerce data hooks on WPXFacets models

Hook families WooCommerce WC_Data emits for XFacets models. Compatibility notes, not XFacets-declared contracts; behavior is unchanged and existing callbacks keep working.

Hooks WPXFacets calls but does not own

WPXFacets also runs these WordPress, WooCommerce and WPML hooks. They belong to those projects and are documented there, not by WPXFacets.

• loop_shop_per_page
• plugin_locale
• woocommerce_after_main_content
• woocommerce_after_shop_loop
• woocommerce_archive_description
• woocommerce_before_main_content
• woocommerce_before_shop_loop
• woocommerce_no_products_found
• woocommerce_shop_loop
• woocommerce_shop_loop_header
• woocommerce_shortcode_after_products_loop
• woocommerce_show_page_title
• woocommerce_sidebar
• woocommerce_taxonomy_objects_product_cat
• wp_search_stopwords
• wpml_active_languages
• wpml_current_language
• wpml_default_language
• wpml_element_language_code
• wpml_object_id
• wpml_post_language_details
• wpml_switch_language

About this reference

Generated from the hooks.json manifest packaged in the released WPXFacets 0.1.18 plugin (schema 1, SHA-256 0fbf625d0c216bf7656b9d03512f314335f2b52f93b217ea7609a8a5d54e1ae0). The contracts themselves are the documentation comments in the plugin source; this page is regenerated from each release’s manifest. Introduction versions come from each contract’s own record: four entries were introduced in 0.1.18, and an introduction version shown as unknown has not been established.