Download the PHP package considbrs-webdev/typesense-search without Composer

Typesense Search

A WordPress plugin that integrates Typesense as the search back-end for WordPress sites running the Municipio theme. It keeps a Typesense collection in sync with your WordPress content in real-time and exposes a configurable front-end search UI.

• Author: Consid Borås AB
• License: MIT
• Requires: WordPress 5.6+, PHP 8.1+

Table of contents

1. What the plugin does
2. Requirements
3. Installation
4. Settings
   • 4.1 PHP constants
   • 4.2 Connection tab
   • 4.3 Settings tab
   • 4.4 Advanced settings tab
   • 4.5 Pinned results page
   • 4.6 Quick search tab
   • 4.7 Statistics tab
   • 4.8 Logging tab
   • 4.9 Status tab
5. Per-post controls
6. WP-CLI commands
7. How indexing works
   • 7.1 Architecture overview
   • 7.2 Services layer
   • 7.3 IndexingHooks
   • 7.4 IndexingRegistry
   • 7.5 IndexingStrategyInterface
   • 7.6 IndexableDocument
   • 7.7 Built-in strategies
   • 7.8 DocumentBuilder and the filter chain
   • 7.9 Enrichers
8. Extensibility
   • 8.1 Add or transform fields via DocumentBuilder filters
   • 8.2 Register a custom WordPress strategy
   • 8.3 Index external content
   • 8.4 Customise hit templates
9. WordPress hooks and filters reference

1. What the plugin does

• Connects to a self-hosted or cloud Typesense instance.
• Automatically indexes WordPress posts (any post type), pages, and PDF files into a single Typesense collection whenever content is published, updated, unpublished, trashed, or deleted.
• Provides a configurable search page UI (Instantsearch-based) that supports faceting, pagination, hit highlighting, and result truncation.
• Provides a quick-search overlay that attaches to configurable CSS selectors on the front-end.
• Can manage pinned search results for specific search phrases using Typesense curation sets (Typesense 30+).
• Can record privacy-conscious local search statistics for both the full search page and quick search, with dashboard widgets and a searchable log under Tools → Search log.
• Exposes WP-CLI commands for bulk indexing, dry-run previews, and index maintenance.
• Is designed to be extended: add fields to existing documents via WordPress filters, write custom indexing strategies for new content types, or index content from external sources (APIs, feeds, third-party systems) alongside WordPress content.

2. Requirements

3. Installation

1. Clone or copy the plugin into wp-content/plugins/typesense-search/.
2. Run composer install inside the plugin directory to install the PHP client.
3. Run npm ci && npm run build to compile front-end assets.
4. Activate the plugin from Plugins in the WordPress admin.
5. Navigate to Settings → Typesense Search and fill in the Connection tab (see §4).

4. Settings

The settings page is at Settings → Typesense Search and is split into seven tabs.

4.1 PHP constants

All five connection settings can be overridden by defining PHP constants before WordPress loads the plugin. The recommended place is a dedicated config file included from wp-config.php (e.g. wp-content/config/typesense.php). This is the standard pattern in Municipio/Helsingborg-stad setups.

When a constant is defined:

• Its value is used instead of whatever is stored in the WordPress database.
• The corresponding field in Settings → Connection is rendered read-only so it cannot accidentally be overwritten from the UI.
• Any form submission that would change the value is silently a no-op.

Supported constants

Setup

Create a config file (e.g. wp-content/config/typesense.php) and include it from wp-config.php:

Blank values — a constant set to an empty string ('') is treated as "not set" and the database option is used instead.

4.2 Connection tab

These settings tell the plugin how to reach your Typesense instance.

The admin key is kept server-side. The search key is the only credential exposed to the browser.

4.3 Settings tab

4.4 Advanced settings tab

This tab collects the detailed search controls: facets, search-field weights, highlight context, truncation, debounce behavior, and search statistics.

Search field weights

Use the Search field weights card to control how strongly each indexed field contributes to result relevance. Each field has an independent scale from 1 (lowest) to 5 (highest):

The plugin passes the configured values to both full and quick searches as Typesense's query_by_weights parameter. Typesense reads those values in the same order as query_by: title,excerpt,content,extra_terms,type_name.

Facets

Configure which fields can be used as facets in the search UI.

Search statistics

Search statistics are optional and stored in a local WordPress table; no Typesense server analytics are required. A completed query is recorded at most once per normalised term and anonymous browser session. The same mechanism is used by the full search page and quick search.

When consent is required, call the following from the consent platform's initial-state callback and whenever that state changes. Existing trackers use the event to start or stop logging; sending false also clears the plugin's session storage.

Expired statistics are removed by a daily WP-Cron event. Ensure WP-Cron runs reliably, or schedule wp typesense prune-search-statistics from server cron.

The Statistics tab shows a search-statistics overview and can clear the stored data. Tools → Search log provides paginated event rows, filters for results and context, sortable date/hit columns, bulk deletion, and a grouped term view with unique-session totals.

Pinned results

When the connected Typesense server supports curation sets (Typesense 30+), the Advanced settings tab shows an Enable pinned results toggle. This feature is off by default. After it is enabled and the settings are saved, the plugin adds a separate Settings → Pinned results admin page for managing the rules.

4.5 Pinned results page

Pinned results let editors promote selected posts for specific search phrases without changing the post title, content, excerpt, or extra search terms. Each rule contains:

• A search phrase.
• A match type: Exact for the phrase itself, or Contains for any query containing the phrase.
• An enabled/disabled state.
• One or more posts, ordered by the position they should occupy in the search results.

Rules are stored locally in WordPress until an administrator syncs them to Typesense. Syncing writes the rules to a Typesense curation set and attaches that set to the configured collection. The manager is only available when both conditions are met:

• Enable pinned results is turned on in Advanced settings.
• The connected Typesense server supports curation sets, which requires Typesense 30 or later.

4.6 Quick search tab

Quick search is a lightweight search overlay that attaches to any element on the page.

4.7 Statistics tab

Shows a live overview of the Typesense collection, including document count and index size, and provides search-statistics summaries when logging is enabled. The collection overview uses the admin API key through an AJAX proxy.

4.8 Logging tab

Shows the latest indexing run and document-level issues captured while indexing. The log can be cleared from this tab.

4.9 Status tab

Checks whether the current configuration is valid and the collection exists. Can create the collection if it is missing.

5. Per-post controls

Every indexed post type records meta fields, managed via a meta box visible in the post editor.

The _typesense_exclude flag is honoured by all built-in strategies. Custom strategies should check it in their shouldIndex() implementation if the same per-post control is desired.

The _typesense_exclude_as_section flag keeps the page indexed, but clears its top_most_parent value when the page is the top-level page in its tree. When the setting is changed, the plugin re-indexes published descendant pages and their attached PDFs so their section facets update immediately.

6. WP-CLI commands

The plugin registers a typesense command when WP-CLI is loaded. All subcommands run after WordPress is fully loaded (--when after_wp_load).

wp typesense index

Bulk-indexes all published posts for the post types enabled in settings.

wp typesense rebuild

Drops the Typesense collection, recreates it from the plugin schema, then optionally re-indexes all content in one operation. Use this whenever the Typesense collection schema needs to change (e.g. after modifying the Municipio/TypesenseSearch/Collection/getSchema filter).

wp typesense clear

Removes indexed documents from the Typesense collection. Deletes are executed as a single bulk request per post type, so the operation is fast even for large collections.

wp typesense prune-search-statistics

Removes local search-statistics rows older than the configured retention period. This is the same cleanup performed by the daily WP-Cron event.

wp typesense populate-search-log

Adds sample local search-log entries for development and testing. Each entry uses a unique session; by default, 70% reuse a small term pool so grouped and popular-search views have meaningful counts.

wp typesense list-external

Lists all external indexing strategies registered by third-party plugins via the Municipio/TypesenseSearch/RegisterStrategies action. Use the printed identifiers with sync-external or clear --only-external.

This command takes no flags.

wp typesense sync-external

Fetches and upserts documents from all registered external indexing strategies (or a single named one). External strategies are registered by third-party plugins via the Municipio/TypesenseSearch/RegisterStrategies action and have no WordPress lifecycle hooks — syncing must be triggered explicitly here or via WP-Cron.

7. How indexing works

This section describes the entire indexing pipeline from a post save through to a Typesense document upsert. Understanding it is essential before writing custom strategies or enrichers.

7.1 Architecture overview

7.2 Services layer

Three shared services are built once by App and injected into every component that needs them.

Replacing the logger — if you want to route plugin log messages to a custom destination (e.g. Sentry, a file, or a test spy), implement LoggerInterface and pass your implementation when registering strategies:

7.3 IndexingHooks

IndexingHooks wires WordPress actions to the registry during bootstrap and also exposes its own actions for external code.

Hooks the plugin listens to

Priority 20 on wp_after_insert_post is intentional — it ensures all meta boxes have written their values before shouldIndex() reads them.

Hooks the plugin exposes for external use

External plugins and themes can trigger indexing operations without depending on any internal class:

PDF attachments have their own lifecycle hooks (add_attachment, edit_attachment, delete_attachment) registered by PdfIndexingStrategy::registerHooks().

7.4 IndexingRegistry

The registry is the central routing table. It holds two separate sets of strategies:

• WordPress strategies (IndexingStrategyInterface) — event-driven; one handles each post saved by WordPress.
• External strategies (ExternalIndexingStrategyInterface) — pull-driven; triggered explicitly by cron, CLI, or any other mechanism. See §7.6 and §8.3.

Built-in registration order (order matters — first match wins for WordPress strategies):

1. PdfIndexingStrategy — matches PDF attachments
2. PostIndexingStrategy — matches everything else that is not an attachment

7.5 IndexingStrategyInterface

Every WordPress indexing strategy implements this contract:

AbstractIndexingStrategy provides default index() and deindex() implementations (upsert and delete via the Typesense PHP client) so concrete strategies only need to implement supports(), shouldIndex(), buildDocument(), and optionally registerHooks().

7.6 IndexableDocument

IndexableDocument is an immutable value object returned by buildDocument(). It guarantees that every document sent to Typesense has at minimum a non-empty id and title field (both required by Typesense).

7.7 Built-in strategies

PostIndexingStrategy ('post')

Handles all non-attachment post types. A post is indexed when:

1. Its post type is enabled in Settings → Typesense Search → Settings.
2. post_status === 'publish'.
3. _typesense_exclude is not set to '1'.

The result at step 3 is filterable via PostIndexingStrategy::FILTER_SHOULD_INDEX (Municipio/TypesenseSearch/Indexer/shouldIndex).

Document fields built by DocumentBuilder::build() (see §7.7):

PdfIndexingStrategy ('pdf')

Handles attachment posts with post_mime_type === 'application/pdf'. A PDF is indexed when:

1. Settings → Index PDF files is enabled.
2. The pdftotext binary is available on the server.
3. _typesense_exclude is not set to '1'.

Text is extracted via pdftotext and capped at DEFAULT_MAX_CONTENT_LENGTH (50 000 characters), overridable via PdfIndexingStrategy::FILTER_MAX_CONTENT_LENGTH.

Additional PDF document field:

7.8 DocumentBuilder and the filter chain

DocumentBuilder::build() assembles the document array for a WordPress post and passes it through two WordPress filter layers before wrapping it in IndexableDocument.

Both filters receive and must return a plain array. IndexableDocument is created after all filters have run.

7.9 Enrichers

Enrichers are classes that hook into the DocumentBuilder filter chain at bootstrap to add fields to specific post types. The plugin ships three:

8. Extensibility

There are three extension levels, from lightest to most powerful.

8.1 Add or transform fields via DocumentBuilder filters

Use this when you want to add extra fields to existing documents without touching any plugin code. No new class is needed.

8.2 Register a custom WordPress strategy

Use this when a post type requires completely custom eligibility logic or a custom document shape that cannot be achieved with DocumentBuilder filters alone.

Step 1 — Write the strategy

AbstractIndexingStrategy provides working index() and deindex() implementations, so you don't need to write those.

Inside a strategy, the injected logger is accessible as $this->logger and the settings repository as $this->getSettings().

Step 2 — Register via the action hook

The action fires after the built-in strategies (pdf, post) are already in the registry. If your strategy's supports() could overlap with PostIndexingStrategy, pass a priority lower than the default (i.e. add_action(..., ..., 5)) to ensure it is registered — and therefore evaluated — first.

Step 3 — Control shouldIndex from outside

The default filter on shouldIndex can be used from any theme or plugin:

8.3 Index external content

Use this when the content you want to index does not come from WordPress at all — for example, an e-services portal, an open-data API, a legacy CMS, or any third-party system.

External strategies implement ExternalIndexingStrategyInterface and are pull-driven: they fetch data on demand rather than reacting to WordPress lifecycle events. They are registered separately on the registry via registerExternal() and triggered by WP-Cron, WP-CLI, or any other explicit call.

Because external documents share the same Typesense collection as WordPress posts, document IDs must be namespaced (e.g. 'eservice-42') to avoid collisions with WordPress post IDs (which are plain integers).

Step 1 — Write the strategy

Extend AbstractExternalIndexingStrategy. You only need to implement three methods:

AbstractExternalIndexingStrategy provides working syncAll() and deindex() implementations. syncAll() iterates fetchItems(), calls buildDocument() on each item, and upserts the result. Individual failures are logged and skipped so the rest of the batch completes.

Notice that $this->logger is already available in the strategy for logging — no error_log() calls needed.

Step 2 — Register via the action hook

After registration, registerAllHooks() will call registerHooks() automatically, scheduling the cron event.

Step 3 — Trigger syncs

Automatic — the cron event set up in registerHooks() fires daily.

Manual via PHP:

Remove a single external document:

The full contract (ExternalIndexingStrategyInterface)

8.4 Customise hit templates

The search results page renders each hit using a small HTML snippet called a hit template. Templates are compiled from Blade view files and injected into the page as <template> elements. The front-end JavaScript selects the right template for each hit based on the document's post_type and replaces placeholder tokens with live values.

Built-in templates

Placeholder tokens

Tokens are {UPPER_SNAKE_CASE} strings embedded in the template HTML. The JavaScript search layer replaces each token with the corresponding value from the Typesense hit document before inserting the card into the DOM.

Core tokens (always available)

When a hit is determined to be external, {SEARCH_HIT_HEADING} automatically appends an external-link icon (fa-up-right-from-square) after the title text. No template changes are needed.

External detection is backward-compatible:

• If the document contains is_external (or isExternal / external), that explicit value is used.
• Otherwise the frontend falls back to comparing the hit URL origin with window.location.origin.

Custom tokens via placeholderMappings filter

You can map additional token names to any field in the Typesense document:

You can then use {SEARCH_HIT_DEPARTMENT} freely in any custom template.

Optional rows: data-js-hide-if-empty

After all placeholders are replaced, the front-end strips any element that has the attribute data-js-hide-if-empty when its text content is empty (after trimming). Use this when optional index fields might be missing, so you do not show orphan icons or empty meta lines.

• The check uses textContent, so <i aria-hidden="true"> and similar decorative nodes do not count as visible text.
• Put the attribute on the wrapper that should disappear as a whole (for example one <span> around icon plus label).

Example:

Mapping post types to templates

By default all posts use the default template. Use the postTypeToTemplate filter to route specific post types to a different built-in or custom template:

Adding a custom template

Step 1 — Register the template key

Step 2 — Point the key to a Blade view

The default view path for a custom key foo is templates.hits.foo, which resolves to views/templates/hits/foo.blade.php relative to each registered view path. You can override the path for any key using the hitTemplateView filter:

Step 3 — Create the Blade file

The file must render a <template> element with a data-js-search-hit-template-{key} attribute so the front-end can find it. Use the Municipio @element directive or plain HTML:

Step 4 — Route the post type to the new template

9. WordPress hooks and filters reference

Actions

External triggering — usage examples

Both hooks are wired in IndexingHooks during bootstrap, so they are available as soon as the plugin is active. Because do_action() on an unregistered hook is a silent no-op, calls made before the plugin loads are safe.

Filters

Indexing filters

Hit template filters