Turbo Search

Enterprise-grade, instant search platform for WordPress & WooCommerce - powered by MySQL FULLTEXT (free, zero setup), Typesense (high-speed C++ search engine), or Elasticsearch.

---

🌟 Key Features

• Triple Engine Support: MySQL FULLTEXT works anywhere out-of-the-box; Typesense & Elasticsearch deliver sub-5ms query response times
• 🛡️ Multi-Tier Fallback Architecture: Automatic failover from Typesense/Elasticsearch → MySQL → WordPress Core native WP_Query; search never fails if a server drops
• 📄 Full-Text Document Search: extracts and indexes full text from PDF (.pdf), Word (.docx), Plain Text (.txt), and Spreadsheets (.csv, .tsv)
• Multi-Post-Type Support: filter by single or multiple post types (Posts, Pages, Products, Attachments, CPTs) in Shortcodes, Widgets, and Gutenberg Blocks
• 📐 3 Results Layout Modes: switch between 📄 List View, ⊞ Grid Cards, and 🗂️ Compact Card modes
• 🛒 WooCommerce 1-Click Buy: instant AJAX "Add to Cart", live inventory, and pricing badges
• ⌨️ Spotlight Command + K Modal: Spotlight search modal overlay with keyboard shortcuts and keyboard navigation
• 🎙️ Web Speech Voice Search: real-time speech-to-text search input (works with HTTPS connection only)
• ⚡ 4-Tier Caching: In-memory browser cache, HTTP 304 ETag, and Redis / Memcached / Transients with intelligent UI cache preservation
• 🖥️ WP-CLI Command Suite: wp turbo-search CLI tool for re-indexing, diagnostics, stats, and DevOps automation
• 🧠 Hybrid AI Vector Search: semantic embeddings with OpenAI (text-embedding-3) or self-hosted Ollama
• Multisite & Multilingual: network-wide search and full WPML / Polylang compatibility
• 🔒 Self-Contained & Private: Pure PHP + WordPress HTTP API, all assets bundled locally without external third-party CDN leaks (100% WordPress.org compliant)

---

📚 Documentation

Complete documentation is available in the docs/ directory:

• 01. Installation & Setup
• 02. Search Features & Shortcodes
• 03. Indexing & Caching Architecture
• 04. Hybrid AI Vector Search
• 05. Developer Hooks & Actions API
• 06. REST API Reference
• 07. Multisite & Multilingual Architecture
• 08. WP-CLI Command Suite Manual
• 09. Complete 72 Settings Reference

---

🚀 Shortcode Reference

[wpts_search placeholder="Search store…" post_types="post,page,product" layout="grid" per_page="8" theme="light"]

Attribute	Default	Description
placeholder	Search…	Input placeholder text
post_types / post_type	(all configured)	Comma-separated post types to query (e.g. post,page,product,attachment)
layout	(from Settings)	Display layout: list (List View), grid (Grid Cards), or card (Compact Card)
per_page	8	Maximum results displayed in dropdown
theme	light	Theme preset: light, dark, minimal, glass
category_tabs	true	Display category multi-filter tabs
quick_cart	true	Show WooCommerce 1-click AJAX Add-to-Cart button
show_voice	true	Show voice search microphone button (works with HTTPS only)
show_type	true	Show post type badge
class	(empty)	Custom CSS container class name

---

REST API

Search

GET /wp-json/wpts/v1/search

Parameter	Type	Default	Description
q	string	-	Required. Search query
post_type	string	all	Filter by post type
lang	string	current	Language code (WPML/Polylang)
per_page	integer	10	Results per page (max 100)
page	integer	1	Page number

Response

{
  "hits": [
    {
      "post_id": 42,
      "title": "Hello <mark>World</mark>",
      "excerpt": "A short excerpt…",
      "post_type": "post",
      "url": "https://example.com/hello-world/"
    }
  ],
  "found": 128,
  "page": 1
}

Re-index (admin only)

POST /wp-json/wpts/v1/reindex

Requires a valid X-WP-Nonce header from a user with manage_options.

---

Typesense Setup

1. Install Typesense on a VPS or use Typesense Cloud.

# Docker (quickest)
docker run -d -p 8108:8108 \
  -v /data:/data typesense/typesense:latest \
  --data-dir /data \
  --api-key=YOUR_SECRET_KEY \
  --enable-cors

2. In WordPress go to Turbo Search → Settings and fill in:

   • Host: your-server-ip or domain
   • Port: 8108
   • Protocol: http or https
   • API Key: your Typesense admin key
   • Collection: wpts_posts (or any name)

3. Click Save Settings then go to Index Manager → Re-index All Posts.

The plugin auto-creates the Typesense collection with the correct schema on first save.

---

Developer Hooks

View all hooks live at Turbo Search → Dev Hooks in your WP admin.

Filters

wpts_indexable_document

Modify the document before it is sent to the index.

add_filter( 'wpts_indexable_document', function ( array $doc, WP_Post $post ) : array {
    // Add a custom field to the index
    $doc['price'] = get_post_meta( $post->ID, '_price', true );
    return $doc;
}, 10, 2 );

wpts_before_index_document

Last-chance filter before writing to Typesense or MySQL.

add_filter( 'wpts_before_index_document', function ( array $doc ) : array {
    $doc['content'] = strip_shortcodes( $doc['content'] );
    return $doc;
} );

wpts_rest_search_results

Modify results before they reach the browser.

add_filter( 'wpts_rest_search_results', function ( array $results, string $query ) : array {
    // Remove results the current user can't read
    $results['hits'] = array_filter( $results['hits'], fn($h) => current_user_can( 'read_post', $h['post_id'] ) );
    return $results;
}, 10, 2 );

wpts_typesense_search_params

Tune Typesense query parameters.

add_filter( 'wpts_typesense_search_params', function ( array $params ) : array {
    $params['num_typos']  = 2;     // allow more typos
    $params['per_page']   = 20;
    return $params;
} );

wpts_typesense_collection_schema

Add custom fields to the Typesense schema (before collection is created).

add_filter( 'wpts_typesense_collection_schema', function ( array $schema ) : array {
    $schema['fields'][] = [ 'name' => 'price', 'type' => 'float', 'optional' => true ];
    return $schema;
} );

wpts_mysql_where_clauses

Add WHERE clauses to the MySQL fallback search.

add_filter( 'wpts_mysql_where_clauses', function ( array $pair, string $q, array $filters ) : array {
    [ $where, $values ] = $pair;
    $where[]  = 'post_type != %s';
    $values[] = 'attachment';
    return [ $where, $values ];
}, 10, 3 );

wpts_register_sample_cpt

Disable the built-in Resource CPT.

add_filter( 'wpts_register_sample_cpt', '__return_false' );

Actions

wpts_booted

Fires after the plugin is fully initialised.

add_action( 'wpts_booted', function ( WPTS\Core $core ) {
    // your bootstrap code
} );

wpts_register_post_types

Register additional CPTs to include in search.

add_action( 'wpts_register_post_types', function () {
    register_post_type( 'product', [ /* ... */ ] );
} );

wpts_after_index_document

Runs after a document is indexed.

add_action( 'wpts_after_index_document', function ( array $doc, bool $ok, string $engine ) {
    if ( ! $ok ) {
        error_log( "WPTS: failed to index post {$doc['id']} via {$engine}" );
    }
}, 10, 3 );

wpts_reindex_complete

Fires when a full re-index finishes.

add_action( 'wpts_reindex_complete', function ( int $count, string $engine ) {
    wp_mail( 'admin@example.com', 'Re-index done', "{$count} posts via {$engine}" );
}, 10, 2 );

wpts_settings_saved

Fires when settings are saved from the admin form.

add_action( 'wpts_settings_saved', function ( array $data ) {
    // flush a custom cache, etc.
} );

---

Multisite

When network-activated:

• The installer creates wp_N_wpts_index tables on every sub-site automatically.
• New sites added to the network get the table immediately (via wp_initialize_site).
• A Network Admin → Turbo Search page shows every site and a one-click "Re-index All Sites" button.
• Network admins can push a single Typesense host/key to all sites at once.

---

Multilingual

WPML

• Posts are indexed with their lang field set via ICL_LANGUAGE_CODE.
• Search results are automatically filtered to the active language.
• Plugin strings are registered with WPML String Translation.
• Hook into wpts_register_wpml_strings to register your own strings.

Polylang

• Posts use pll_current_language() as the lang field.
• The wpts_resource CPT is automatically registered as translatable.
• All search queries are filtered to the current Polylang language.

---

File Structure

turbo-search/
├── turbo-search.php          ← Plugin header, constants, autoloader, boot
├── uninstall.php                ← Cleanup on plugin deletion
├── includes/
│   ├── class-core.php           ← Singleton: wires all subsystems
│   ├── class-installer.php      ← DB table creation, default options
│   ├── ajax-handlers.php        ← wp_ajax_* handlers
│   ├── admin/
│   │   ├── class-settings.php   ← Option read/write/sanitise
│   │   └── class-admin-page.php ← Admin menus, settings form, index manager
│   ├── api/
│   │   └── class-rest-search.php← REST endpoint: /wpts/v1/search
│   ├── cache/
│   │   ├── class-typesense.php  ← Typesense adapter (REST via WP HTTP API)
│   │   └── class-mysql.php      ← MySQL FULLTEXT fallback
│   ├── cpt/
│   │   └── class-cpt-manager.php← CPT registration
│   ├── hooks/
│   │   └── class-hooks-manager.php ← Internal hooks + public hooks reference
│   ├── i18n/
│   │   └── class-i18n-loader.php← Text domain, WPML, Polylang
│   └── multisite/
│       └── class-network.php    ← Network admin page
├── assets/
│   ├── css/
│   │   ├── search.css           ← Frontend instant-search styles
│   │   └── admin.css            ← Admin page styles
│   └── js/
│       ├── search.js            ← Vanilla JS instant search widget
│       └── admin.js             ← Admin UI helpers
├── templates/
│   └── shortcode.php            ← [wpts_search] shortcode + WP widget
└── languages/
    └── turbo-search.pot      ← Translation template

---

License

GPL-2.0-or-later - see https://www.gnu.org/licenses/gpl-2.0.html

---

Dashboard & Analytics

Admin Menu Structure

Turbo Search
├── 📊 Dashboard          ← KPI cards, volume chart, top queries, index status
├── ⚙️  Settings          ← General, post types, Typesense, frontend config
├── 📊 Tracking           ← Full search log, top queries, zero results, index events
├── ⚡ Cache              ← Driver config, Redis, Memcached, flush controls
├── 📄 Index Manager      ← Re-index, current index count
├── 🔗 Dev Hooks          ← All filters & actions reference
└── [Network Admin]       ← Multisite network overview (multisite only)

---

Dashboard Page

The main overview page shows:

Widget	Description
9 KPI Cards	Total searches, cache hit rate, cache hits/misses, indexed posts, posts indexed/deleted, zero-result searches, cache flushes
Search Volume Chart	14-day bar chart (total / cached / zero-results) with 7/14/30 day selector
Top Searches	Most searched queries with avg results, speed, cache hit rate bar
Zero-Result Queries	Content gaps - queries that returned nothing, with "Create Post" shortcut
Index Status	Total indexed count and per-post-type breakdown
Status Bar	Active search engine + cache driver + TTL at a glance

---