Developer Reference
This is the technical reference for extending Super Speedy Search from your own code. It covers the sss_* filters and actions, the wp-config constants, the theme template overrides, the WP-CLI command, and the MCP control surface. Every item here has been checked against the plugin source, so you can rely on the names and defaults exactly as written.
Everything here is optional. Super Speedy Search works from its admin settings alone, so reach for these hooks only when the settings screens do not expose what you want.
Most constants here mirror a setting on the Advanced Options tab. When a constant is defined in wp-config.php it takes priority over the saved option, which is useful for locking behaviour across staging and production, or setting a value before the admin UI exists.
Filters and actions
All of these use the sss_ prefix. The table lists what each one receives and what it controls. Filters return a value; the two multi_search entries are actions and return nothing.
| Hook | Type | What it receives / controls | |
|---|---|---|---|
sss_enabled | filter (bool) | Master switch, default true. Return false to disable every SSS hook on both the front end and the admin, leaving WordPress core search untouched. Checked at init on both sss_frontend_init and sss_backend_init. | |
sss_post_types | filter (array) | The final list of post types Super Speedy Search treats as searchable. Receives the result of get_post_types() (objects or names, depending on the caller). Add or remove entries to change which post types are indexed and searched. | |
sss_post_types_args | filter (array) | The $args array passed into get_post_types() before the list is built. Defaults to array( 'public' => true, 'exclude_from_search' => false ). | |
sss_tax | filter (array) | The taxonomy objects offered for taxonomy suggestions and taxonomy-combination features. Receives the output of get_taxonomies( $args, 'objects' ). | |
sss_tax_args | filter (array) | The $args passed to get_taxonomies() when building that list. Defaults to array( 'show_ui' => true, 'public' => true ). | |
sss_meta_keys | filter (array) | The final list of meta keys surfaced in the admin meta-keys picker. Applied both on the fast first-load path and after the exhaustive scan. | |
sss_meta_keys_whitelist | filter (array) | The curated list of commonly-searched meta keys (SKU, GTIN, MPN, brand, model, and similar) that the admin checks instantly on first load before you click “Fetch all meta keys”. Extend it to make your own keys appear without the full scan. | |
sss_meta_keys_query | filter (string) | The full SQL query used by the exhaustive “fetch all meta keys” scan of wp_postmeta. Filter it to change which keys are excluded from the picker. | |
sss_posts_search_where | filter (string, WP_Query) | The WHERE clause SSS has built for the current search query, plus the $wp_query. Append your own SQL conditions to further constrain search results. | |
sss_before_multi_search | action | Fires at the top of the sss-multi-search.php template, before the mixed-section results render. | |
sss_after_multi_search | action | Fires at the bottom of the same template, after the sections render. | |
sss_combination_meta_axis_url | filter (string\ | null, context) | For taxonomy-combination suggestions that use a meta value as an axis. Receives null and a context array (meta_key, meta_value, query_var, post_type, taxonomy_pairs, row). Return a full http(s) URL to replace the suggestion link entirely, or a ?x=y / &x=y fragment to merge query args onto the default URL. |
sss_woo_admin_product_meta_keys | filter (array) | Meta keys to extend the WooCommerce wp-admin product-list search over (edit.php?post_type=product&s=...). Defaults to an empty array, so admin meta search is off until you supply keys here. | |
sss_mcp_rebuild_time_budget | filter (int) | Seconds a single MCP rebuild-index call may spend running SQL before it returns a cursor for the next batch. Default 20, sized well under a typical 60-second HTTP timeout. |
Constants
These are wp-config.php constants. Most of them mirror a setting on the admin Advanced Options tab: if the constant is defined it takes priority over the saved option, which is handy for locking behaviour across environments or setting it before the admin UI exists. Only SSS_ENABLE_WOOSA and SSS_VERBOSE are actively defined with defaults in defines.php; the rest are inert unless you define them yourself in wp-config.php.
| Constant | Type | Meaning |
|---|---|---|
SSS_MAX_PER_TAX | int | Caps how many taxonomy-suggestion rows are returned per taxonomy in the ajax results. Overrides the “Max Per Tax” option. |
SSS_FAST_VISIBILITY_CHECK | bool | Overrides the “Fast Visibility Check” option that governs how post visibility is verified in results. |
SSS_HIDE_AJAX_ON_SCROLL | bool | Overrides the “Hide Ajax on Scroll” option, hiding the as-you-type panel when the visitor scrolls. |
SSS_HIDE_SSS_LOGO | bool | Overrides the “Hide SSS Logo” option, removing the Super Speedy Search logo from the results panel. |
SSS_FORCE_OPTIMIZE_IN_BUILD | bool | Overrides the “Force Optimize in Build” option that controls table optimisation during a rebuild. |
SSS_FORCE_SUGGESTIONS_REBUILD | bool | Overrides the “Force Suggestions Rebuild” option that forces the suggestions tables to be rebuilt. |
SSS_ONLY_SEARCH_TITLE | bool | Deprecated after version 4.38. Restricted search to the post title only. Use the column selection in the admin instead; the plugin will auto-select the title column if this is set. |
SSS_ENABLE_WOOSA | bool | Default false. Set true if you use the Woosa VidaXL DS plugin, to enable its external images inside the Ultra Ajax panel. |
SSS_VERBOSE | bool | Default false. Set true to enable verbose debug logging to error_log. Only takes effect when WP_DEBUG is also enabled. |
Template overrides
The as-you-type ajax results are rendered through a Gamajo template loader subclass, SSS_Template_Loader, whose theme directory is sss-templates and whose filter prefix is sss. The loader checks the child theme first, then the parent theme, then the plugin’s own templates/ folder, so you only need to copy the one file you want to change. To override a template, copy it into a sss-templates/ folder in your theme, keeping the same filename:
wp-content/themes/your-theme/sss-templates/ajax-search-results.php
wp-content/themes/your-theme/sss-templates/ajax-search-results-grid.phpajax-search-results.php renders the list layout and ajax-search-results-grid.php renders the grid layout, chosen per post type by the “display template” setting.
The mixed-section, full-page search templates use a second, separate lookup (locate_sss_template()). These load from a super-speedy-search/ folder in your theme (child theme before parent), again falling back to the plugin’s templates/ folder:
wp-content/themes/your-theme/super-speedy-search/sss-multi-search.php
wp-content/themes/your-theme/super-speedy-search/sss-multi-search-section.php
wp-content/themes/your-theme/super-speedy-search/sss-multi-search-section-product.phpsss-multi-search.php is the wrapper for the mixed-sections layout (where the sss_before_multi_search and sss_after_multi_search actions fire). sss-multi-search-section.php renders one post-type section, and a sss-multi-search-section-{post_type}.php file, if present, wins for that specific post type (for example the bundled sss-multi-search-section-product.php for WooCommerce products). Note the two mechanisms use different theme folder names: sss-templates/ for the ajax panel, super-speedy-search/ for the full-page sections. The full-search-results.php file also ships in templates/, but it is only referenced by a currently-inactive code path and is not wired onto a theme-override route, so do not rely on overriding it.
For which full-page layout runs (single ranked list versus mixed sections), see Searching multiple post types in full-page search results: Single ranked list vs Mixed sections.
WP-CLI
Super Speedy Search registers one WP-CLI command:
wp sss rebuild [<scope>] [force]The scope defaults to all and accepts all, search, suggestions, taxonomy_suggestions, or cancel. Adding force waits through any in-flight cancellation rollback rather than bailing out. This is the reliable way to rebuild large indexes without hitting a web-server timeout, and it is documented fully in Rebuilding Super Speedy Search tables from the command line: wp sss rebuild.
The end-to-end regression suite is run from the shell, not from WP-CLI, via bash .tests/run-tests.sh (see the harness README in .tests/). An older wp sss run-tests command exists only in the archived test tooling and is not registered by the current plugin.
MCP and AI control
Super Speedy Search exposes a set of WordPress Abilities API abilities under the sss/ namespace (for example describe-search-config, test-query, get-weights, set-weights, upsert-synonyms, get-index-status and rebuild-index). These let an AI agent read your search configuration, run real queries to inspect the ranking and score breakdown, adjust weights and synonyms, and drive an index rebuild in timed batches. A bundled stdio bridge (tools/sss-abilities-mcp-bridge.mjs) connects any MCP client to those abilities over the core Abilities REST API using an Application Password, with no MCP Adapter plugin required on the site.
The stdio bridge talks straight to the core Abilities REST API with an Application Password, so you do not need the MCP Adapter plugin installed on the site. That keeps the AI-control surface working without adding another plugin to production.
For the full walkthrough of connecting a client and what each ability does, see Controlling Super Speedy Search from an AI agent (MCP). For the settings these hooks and abilities operate on, see Main Super Speedy Search Settings, Search Meta Keys and Adjusting Super Speedy Search Weights.
Comments