Documentation · 1.0.7

PrismSearch — Complete Guide

Everything you need to configure, extend and customise PrismSearch on your WordPress site.

Content sources to index

Select the public post types that should be indexed and returned by search. The default selection is Posts and Pages, but the current plugin also allows any registered public custom post type.

This can include products, portfolios, events and other public content types. Only selected post types are included in search results and live index updates.

Taxonomies to index

Select public taxonomies whose terms should be indexed as separate search results. A matching term links to its term archive page.

Leave this setting empty if you want search results to contain post-type content only.

Frontend search modes Pro

PrismSearch Pro provides three frontend search modes.

The default REST API mode uses the normal WordPress REST request lifecycle and offers the broadest compatibility with themes and plugins.

REST Search Fast Path is an optional lower-overhead mode for eligible anonymous frontend searches. Direct Pro sends requests to pro/search.php and loads WordPress with SHORTINIT.

Changing the search mode does not change the indexed content and does not require an index rebuild.

REST Search Fast Path Pro

REST Search Fast Path uses a managed MU-plugin to handle eligible anonymous PrismSearch requests earlier in the WordPress bootstrap process, after MU-plugins are loaded but before normal plugins and the active theme are loaded.

The MU-plugin is installed and managed through the WordPress Filesystem API when Fast Path is selected. If Fast Path is unavailable, PrismSearch falls back to the normal REST search path.

Authenticated or nonce-protected requests are not handled by Fast Path. Fast Path is also disabled on WordPress multisite installations.

Direct endpoint performance Pro

The Direct Pro endpoint avoids most of the normal WordPress bootstrap process, making it significantly faster than the standard REST API endpoint.

Because it searches PrismSearch’s prebuilt inverted index, query processing can remain below one millisecond on a properly configured server, even with more than 100,000 indexed posts.

Complete HTTP response time still depends on the server, database, network latency and hosting environment.

Searchable meta keys Pro

This field appears after PrismSearch Pro has been registered. Search the available post-meta keys and select the values that should be added to the searchable index.

Use it for ACF fields, SKU, EAN, brand, model and other stored metadata. The selector scans metadata belonging to the currently selected post types.

After adding or removing searchable meta keys, build the complete index again. WooCommerce meta keys are not selected automatically.

Frontend meta keys

Select meta keys whose values should be included in frontend search responses and rendered in the live result list.

Frontend meta values are display-only unless the same key is also selected under Searchable meta keys. Changing display-only frontend meta keys does not require rebuilding the index.

Minimum characters

Search starts after the visitor types the configured number of characters. The default is 2, and the accepted range is 1 to 10.

The value can be overridden for an individual shortcode with min_chars.

Results limit

Sets the maximum number of live results returned per request. The default is 8, and the accepted range is 1 to 20.

The value can be overridden for an individual shortcode with limit.

Disable frontend CSS

By default PrismSearch loads assets/frontend.css. Enable this option when your theme provides all search-box and result styling.

You can also control stylesheet loading programmatically:

add_filter( 'prismsearch_load_frontend_css', '__return_false' );

Redirect on Enter

When enabled, pressing Enter in the live search input opens the full WordPress search results URL for the typed query, for example /?s=example.

This setting controls the redirect only. It does not automatically replace the WordPress search query unless Override default WordPress search is also enabled.

Voice search

Enable optional microphone input through the browser Web Speech API. Voice search is disabled by default and can be overridden for an individual shortcode with voice_search.

The microphone is shown only in a secure context and a supported browser. Chrome, Edge and Safari are supported; Firefox and Opera are not supported, so the microphone remains hidden in those browsers.

Automatic theme integration

Enable this option to display PrismSearch through supported theme search locations without adding a shortcode. The option is disabled by default, and the integration layer is not loaded while it is disabled.

Twenty Twenty-Five, Storefront and Astra are supported. Existing classic WordPress search forms and Core Search blocks can also be replaced. In Astra, PrismSearch uses the native Header Builder Search element so it can be moved and customised in the header editor.

Override default WordPress search

When enabled, the main WordPress search query uses PrismSearch post results instead of the default WordPress text-search SQL.

The override currently considers up to 200 indexed post-type results and preserves PrismSearch result order. Indexed taxonomy terms remain available in live search but are not inserted into the standard WordPress posts loop.

WooCommerce price formatting Pro

When PrismSearch Pro is registered and WooCommerce is available, selected price metadata is formatted with the store currency symbol, currency position, decimal separator, thousands separator and decimal count.

Select the required keys under Frontend meta keys, for example _price, _regular_price or _sale_price. These fields are not selected automatically.

WCML multi-currency Pro

When WCML exposes an active frontend currency, PrismSearch includes that currency and its available exchange rate in Pro search requests and resolves selected price values for the active currency where possible.

NLP language

Select the primary language used for tokenisation and search processing. Language processors can provide normalisation, stopword handling and language-specific token processing.

Bundled processors include English, German, French, Spanish, Portuguese, Italian, Dutch, Polish, Romanian, Russian, Ukrainian, Japanese, Chinese, Korean, Arabic, Persian, Hebrew, Thai and additional European and Asian languages.

Without multilingual mode, this single language is used for the complete index.

Multilingual indexing Pro

After Pro registration, enable multilingual support and select the languages that should be indexed. PrismSearch stores a language mapping for each indexed post and taxonomy term.

WPML and Polylang are used automatically when available. When an object-specific language cannot be resolved, the configured NLP language is used as the fallback.

Rebuild the complete index after enabling multilingual support or changing the selected languages.

Language-aware frontend filtering Pro

When multilingual support is enabled, frontend search resolves the current language and filters matching objects and terms to that language before the result limit is applied.

The Language panel also displays the language currently detected for frontend filtering.

Matching strategies

Choose the matching behaviour that fits how visitors search your site. Normal exact and normalised matches remain the strongest signals, while the fuzzy strategies broaden matching when the query contains mistakes or incomplete words.

Normal / exact matching: the baseline path for exact and normalised token matches.
Typo tolerance: handles typing mistakes with adaptive typo matching.
Partial / prefix matching: matches incomplete words and typed prefixes.
Aggressive fuzzy: combines typo tolerance with partial/prefix matching for the broadest fuzzy behaviour.

Normalised, case-insensitive matching

Version 1.0.7 normalises matching so case differences do not prevent otherwise equivalent indexed tokens from matching.

Exact and normalised matches are kept above partial and fuzzy matches in the relevance tiers, helping strong text matches remain prominent even when broader matching is enabled.

Adaptive typo tolerance

Typo tolerance is intended for misspelled searches. Version 1.0.7 uses adaptive typo matching as part of the current relevance system.

Use Aggressive fuzzy when you want typo handling and incomplete-word matching together.

Partial and prefix matching

Partial / prefix matching is useful when visitors type only the beginning of a word. It can return relevant indexed tokens before the complete word has been entered.

Broader fuzzy modes can produce more candidate matches. PrismSearch uses relevance tiers so exact and normalised matches remain stronger than partial and fuzzy matches.

Available ranking modes

Mode	Purpose
Relevance	Orders results by PrismSearch search relevance and match quality.
Popularity	Orders results using the available popularity signal.
Rating	Orders results using the available rating signal.
Newness	Prioritises newer content.
WooCommerce menu order	Uses WooCommerce product menu ordering where applicable.
Custom weights	Lets configured ranking weights influence the final result order.

Relevance tiers and fuzzy matches

The ranking system works with the 1.0.7 fuzzy logic. Exact and normalised matches remain stronger than partial and fuzzy matches, so broader matching does not automatically outrank a stronger text match.

Ranking debug

An optional ranking debug mode is available for inspecting ranking behaviour while tuning the result order and custom weighting.

Use it during configuration and testing when you need to understand why one result is ordered ahead of another.

The new fuzzy and ranking logic remains compatible with Pro multilingual search, searchable metadata, WooCommerce/WCML processing and the Direct Pro search path.

Frontend request protection

Standard REST and Direct Pro search requests use PrismSearch frontend request validation and reject missing or invalid request tokens where that validation path applies.

REST Search Fast Path is limited to eligible anonymous requests. Authenticated or nonce-protected requests bypass Fast Path and continue through the normal WordPress request path instead.

Request validation is not user authentication and is not a complete bot-blocking system.

Search rate limit

Sets the maximum number of frontend searches allowed per server-visible IP address per minute. The default is 50.

The accepted range is 0 to 1000. Use 0 to disable rate limiting.

Index batch size

Controls how many objects are processed in each admin AJAX indexing batch. The default is 25, and the accepted range is 1 to 500.

Smaller batches reduce the work performed by each request. Larger batches can finish with fewer requests but require more work per request.

Live index update

Enabled by default. PrismSearch updates selected post types and selected taxonomy terms when supported save, update, quick-edit, trash or delete events run.

Normal day-to-day edits therefore do not require a complete rebuild when live updates are enabled.

REST API live updates

Disabled by default. Enable this when content created, updated or deleted through WordPress REST API requests must also trigger live index maintenance.

Index information

The Advanced panel displays the newest indexed timestamp, total index-table size, index-table count and estimated index-row count.

These values are diagnostic information reported from the PrismSearch tables and the database engine.

Pro registration Pro

Enter the registration number under Settings → PrismSearch → Registration. A valid registration enables Pro settings and licence-based updates.

If a previously registered licence expires, Pro features remain active on that site, while licence-protected updates remain unavailable until renewal.

Basic usage

[prismsearch]

All attributes

[prismsearch min_chars="2" limit="8" placeholder="Search..." enter_redirect="1" voice_search="1"]

Attribute	Default	Description
`min_chars`	Global setting; `2` on a new install	Minimum typed characters before a request is sent. Effective range: `1`–`10`.
`limit`	Global setting; `8` on a new install	Maximum live results returned. Accepted range: `1`–`20`.
`placeholder`	`Search...`	Placeholder and accessible label for the search input.
`enter_redirect`	Global setting	Truthy values such as `1`, `true`, `yes` or `on` enable Enter-key redirection. Other values disable it.
`voice_search`	Global setting	Truthy values such as `1`, `true`, `yes` or `on` enable voice search for this shortcode. Other values disable it.

The minimum-character setting controls when a request is sent. NLP tokenisation and stopword processing are applied separately by the selected language processor.

When to build the index

After first installing and configuring PrismSearch
After changing selected post types or taxonomies
After changing the NLP language
After adding or removing Pro searchable meta keys
After enabling multilingual support or changing indexed languages
After bulk imports or migrations that did not trigger live index updates

Changing the frontend search mode, result limit, minimum characters, stylesheet setting or display-only frontend meta keys does not require a rebuild.

Automatic updates

With Live index update enabled, PrismSearch maintains individual selected posts and taxonomy terms during supported WordPress save, update, trash and delete events.

Enable REST API live updates when those events must also run during REST API content changes.

Index progress and recovery

The admin screen builds the index through consecutive batches and shows current progress. Saved build state allows an interrupted active build to continue after the admin page is refreshed.

Build duration depends on content volume, content size, selected taxonomies, searchable metadata, the configured batch size, database performance and server resources.

Pause and continue

Current releases provide Pause and Continue controls for index builds, allowing an active rebuild to be temporarily suspended and resumed without starting again from the beginning.

Stop indexing

Stop is available while a build is active or paused. Stopping ends the current build and resets its progress state without using the Clear Index action.

Clear index

The Clear Index button removes PrismSearch indexed data. Search returns no indexed results until the index is built again.

Basic command

Run a complete reindex with:

wp prismsearch reindex

Override batch size and worker count

Pass command-line options when a particular rebuild needs different values from the configured indexing settings:

wp prismsearch reindex --batch=100 --threads=4

Option	Accepted values	Description
`--batch`	`1`–`500`	Objects processed per batch. When omitted, the configured index batch value is used.
`--threads`	`1`–`6`	Parallel workers. When omitted, the configured index worker value is used.

Parallel worker requirement

Parallel CLI workers require the PHP CLI pcntl extension. If pcntl is unavailable, PrismSearch falls back to a single worker.

Index locking and Pro filters

The CLI command uses the same index lock and Pro indexer filters as the admin index builder. An admin rebuild and a CLI rebuild therefore cannot intentionally run at the same time.

How it works

Create a template/prismsearch/ directory inside the active theme. PrismSearch checks the child theme first, then the parent theme and finally the plugin templates.

your-theme/
└── template/
    └── prismsearch/
        ├── item.php       ← one live result item
        ├── blocks.php     ← frontend metadata and optional Pro slots
        ├── empty.php      ← no-results message
        └── show-all.php   ← link to the full search page

The PHP templates are rendered once when the shortcode is generated. Individual AJAX results are inserted later in JavaScript by replacing placeholders. Per-result PHP variables such as $item['id'] or $item['meta'] are not available.

Available placeholders

Placeholder	Template	Description
`__URL__`	`item.php`	Escaped post permalink or taxonomy-term archive URL
`__TITLE_HTML__`	`item.php`	Escaped title with search-term highlighting markup
`__TITLE_ATTR__`	`item.php`	Escaped plain title suitable for an HTML attribute
`__EXCERPT_HTML__`	`item.php`	Escaped excerpt with highlighting markup
`__FEATURED_IMAGE__`	`item.php`	Escaped featured-image URL; the default image wrapper is removed when no image is available
`__BLOCKS_HTML__`	`blocks.php`	Rendered frontend meta fields selected in settings
`__ADD_TO_CART_HTML__`	`item.php` or `blocks.php`	Pro WooCommerce add-to-cart markup when the placeholder is included
`__SEARCH_URL__`	`show-all.php`	Full WordPress search URL for the current query

Minimal item.php example

<?php
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}
?>
<div class="prismsearch-item">
    <a class="prismsearch-item-title" href="__URL__" title="__TITLE_ATTR__">
        __TITLE_HTML__
    </a>

    <span class="prismsearch-item-excerpt">__EXCERPT_HTML__</span>
    <span class="prismsearch-item-blocks">__BLOCKS_HTML__</span>
</div>

Template output is sanitised against PrismSearch’s allowed HTML-element and attribute list before it is embedded in the page.

Core filters

Filter	Arguments	Description
`prismsearch_load_frontend_css`	`$load, $settings`	Enable or disable the default frontend stylesheet.
`prismsearch_shortcode_defaults`	`$defaults`	Change shortcode defaults before shortcode attributes are applied.
`prismsearch_frontend_search_url`	`$url`	Change the frontend search-request URL.
`prismsearch_frontend_i18n`	`$strings`	Add or change strings passed to the frontend script.
`prismsearch_frontend_meta_labels`	`$labels`	Add the meta-key-to-label map passed to the frontend script.
`prismsearch_meta_label`	`$label, $key`	Modify each label already present in the frontend meta-label map.
`prismsearch_frontend_meta`	`$meta, $post_ids, $meta_keys, $settings, $wpdb`	Modify frontend metadata after values have been loaded for result posts.
`prismsearch_enabled_frontend_meta_keys`	`$meta_keys, $settings`	Modify the frontend meta keys used by search responses.
`prismsearch_index_post_title`	`$title, $post`	Modify a post title before tokenisation and indexing.
`prismsearch_index_post_content`	`$content, $post`	Modify the searchable post-content string before tokenisation and indexing.
`prismsearch_supported_post_types`	`$post_types, $settings`	Modify the discovered list of supported public post types.
`prismsearch_reindex_on_object_terms_set`	`$should_reindex, $object_id, $terms, $tt_ids, $taxonomy, $append, $old_tt_ids`	Decide whether changing an object’s terms should reindex that post.
`prismsearch_detected_languages`	`$languages`	Add language-code and label pairs backed by the generic processor.
`prismsearch_normalized_settings`	`$settings, $saved`	Modify normalised core settings.
`prismsearch_sanitized_settings`	`$output, $input, $old, $available_languages`	Modify core settings during admin form sanitisation.
`prismsearch_indexer_service`	`$indexer, $wpdb, $settings`	Replace or extend the indexing service.
`prismsearch_search_service`	`$service, $wpdb, $settings`	Replace or extend the search service.

Pro filters

Filter	Arguments	Description
`prismsearch_enabled_searchable_meta_keys`	`$meta_keys, $settings`	Modify the Pro meta keys added to the searchable index.
`prismsearch_index_post_meta_text`	`$meta_text, $post_id, $post, $settings`	Modify the combined searchable metadata text before Pro indexing.
`prismsearch_enabled_languages`	`$languages, $settings`	Modify the languages enabled for Pro indexing.
`prismsearch_search_language`	`$language, $settings`	Modify the language used for frontend result filtering.
`prismsearch_object_language`	`$language, $object_type, $object_id, $object_subtype, $settings`	Resolve or replace the language stored for an indexed object or term.
`prismsearch_current_language_raw`	`$language`	Provide a raw current-language value before fallback processing.
`prismsearch_post_index_url`	`$url, $post_id, $language, $settings`	Modify the URL stored for a Pro-indexed post.
`prismsearch_frontend_price_format`	`$price_format`	Modify WooCommerce-style price-format data passed to the Pro frontend script.

Actions

Action	Arguments	Description
`prismsearch_before_index_post`	`$post_id`	Runs before a post is indexed.
`prismsearch_after_index_post`	`$post_id`	Runs after a post has been indexed.
`prismsearch_before_build_index`	None	Runs before a complete admin index build starts.
`prismsearch_after_build_index`	None	Runs after a complete admin index build finishes.
`prismsearch_after_hero`	None	Outputs integration content after the PrismSearch admin hero.
`prismsearch_settings_tabs`	`$settings`	Allows integrations to output additional settings-tab buttons.
`prismsearch_settings_content_fields`	`$settings, $option_key, $post_type_choices, $taxonomy_choices`	Allows integrations to output fields in the Content panel.
`prismsearch_settings_panels`	`$settings, $option_key`	Allows integrations to output additional settings panels.

Example: add custom text before indexing

add_filter( 'prismsearch_index_post_content', function( $content, $post ) {
    if ( $post instanceof WP_Post && $post->post_type === 'event' ) {
        $content .= ' event calendar';
    }

    return $content;
}, 10, 2 );

Rebuild the index after adding or changing indexing filters so existing content is processed again.

Example: change shortcode defaults

add_filter( 'prismsearch_shortcode_defaults', function( $defaults ) {
    $defaults['limit'] = '12';
    $defaults['placeholder'] = 'Search products...';

    return $defaults;
} );

Add labels for custom meta keys

add_filter( 'prismsearch_frontend_meta_labels', function( $labels ) {
    $labels['custom_brand']  = __( 'Brand', 'your-textdomain' );
    $labels['product_model'] = __( 'Model', 'your-textdomain' );
    $labels['ean_code']      = __( 'EAN', 'your-textdomain' );

    return $labels;
} );

Modify an existing label

The prismsearch_meta_label filter runs for labels already present in the frontend label map. WooCommerce Pro adds labels for _price, _regular_price, _sale_price and _sku.

add_filter( 'prismsearch_meta_label', function( $label, $key ) {
    if ( $key === '_sku' ) {
        return __( 'Product code', 'your-textdomain' );
    }

    return $label;
}, 10, 2 );

Plugin translation files

PrismSearch uses the prismsearch text domain. Standard WordPress translation tools can scan the plugin source and generate a translation catalogue.

Compiled translation files can be stored in wp-content/languages/plugins/ using the normal plugin naming convention:

prismsearch-de_DE.po
prismsearch-de_DE.mo
prismsearch-fr_FR.po
prismsearch-fr_FR.mo

Step 1 — Override blocks.php

Create template/prismsearch/blocks.php in your active theme or child theme:

<?php
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}
?>
<span class="prismsearch-item-blocks">__BLOCKS_HTML__</span>
<span class="prismsearch-item-cart">__ADD_TO_CART_HTML__</span>

The placeholder is replaced in the browser. Do not call wc_get_product() or expect per-result PHP variables inside the template.

Step 2 — Style the generated link

The generated anchor includes the prismsearch-add-to-cart, add_to_cart_button and ajax_add_to_cart classes.

.prismsearch-item-cart {
    display: block;
    margin-top: .35rem;
}

.prismsearch-add-to-cart {
    display: inline-flex;
    align-items: center;
    justify-content: center;
    padding: .35rem .8rem;
    border-radius: 6px;
    background: #2d60f0;
    color: #fff;
    font-size: .78rem;
    font-weight: 600;
    text-decoration: none;
}

.prismsearch-add-to-cart:hover {
    background: #4d7cf4;
    color: #fff;
}

Step 3 — Understand the current product limitation

The current Pro frontend generates simple-product AJAX add-to-cart markup for indexed WooCommerce product results. It does not inspect the product type, stock state or purchasability before generating the link.

Use the placeholder only when the indexed product results are suitable for direct simple-product add to cart. Variable, grouped, external or otherwise non-direct-purchase products should normally link to the product page instead.

WooCommerce’s frontend AJAX add-to-cart script must also be available on the page for AJAX cart behaviour.

Need help?

Still have questions?

Check the FAQ on the homepage or reach out via the support forum on WordPress.org.

Get Pro Version Support Forum

PrismSearch — Complete Guide

Content Indexing

Content sources to index

Taxonomies to index

Frontend search modes Pro

REST Search Fast Path Pro

Direct endpoint performance Pro

Searchable meta keys Pro

Frontend meta keys

Frontend Settings

Minimum characters

Results limit

Disable frontend CSS

Redirect on Enter

Voice search

Automatic theme integration

Override default WordPress search

WooCommerce price formatting Pro

WCML multi-currency Pro

NLP & Language

NLP language

Multilingual indexing Pro

Language-aware frontend filtering Pro

Fuzzy Search

Matching strategies

Normalised, case-insensitive matching

Adaptive typo tolerance

Partial and prefix matching

Result Ranking

Available ranking modes

Relevance tiers and fuzzy matches

Ranking debug

Security

Frontend request protection

Search rate limit

Advanced Settings

Index batch size

Live index update

REST API live updates

Index information

Pro registration Pro

Shortcode Reference

Basic usage

All attributes

Building & Rebuilding the Index

When to build the index

Automatic updates

Index progress and recovery

Pause and continue

Stop indexing

Clear index

WP-CLI Full Reindex

Basic command

Override batch size and worker count

Parallel worker requirement

Index locking and Pro filters

Template Override

How it works

Available placeholders

Minimal item.php example

Hooks & Filters

Core filters

Pro filters

Actions

Example: add custom text before indexing

Example: change shortcode defaults

Translating Meta Names

Add labels for custom meta keys

Modify an existing label

Plugin translation files

Add to Cart Button in Results

Step 1 — Override blocks.php

Step 2 — Style the generated link

Step 3 — Understand the current product limitation

Still have questions?