PHPackages                             soderlind/loupe-search - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. soderlind/loupe-search

ActiveWordpress-plugin

soderlind/loupe-search
======================

Loupe Search is a powerful search enhancement plugin for WordPress that delivers fast, accurate, and typo-tolerant search results. Loupe Search exposes a developer-friendly API so you can build your own search UI.

1.2.0(today)30[2 PRs](https://github.com/soderlind/loupe-search/pulls)GPL-2.0-or-laterPHPCI passing

Since Jul 26Pushed todayCompare

[ Source](https://github.com/soderlind/loupe-search)[ Packagist](https://packagist.org/packages/soderlind/loupe-search)[ Docs](https://github.com/soderlind/wp-loupe)[ Fund](https://paypal.me/PerSoderlind)[ RSS](/packages/soderlind-loupe-search/feed)WikiDiscussions main Synced today

READMEChangelog (3)Dependencies (4)Versions (11)Used By (0)

Loupe Search - Enhanced WordPress Search
========================================

[](#loupe-search---enhanced-wordpress-search)

A search enhancement plugin for WordPress that builds a fast, typo-tolerant index and exposes a [developer-friendly API](https://github.com/soderlind/loupe-search/blob/main/docs/search-api.md) so you can build your own search UI. **Loupe Search works out of the box with WordPress’s standard search.**

> **Renamed from WP Loupe.** Loupe Search is the successor to the **WP Loupe** plugin. Existing installs upgrade seamlessly, and the legacy filters, REST namespace, CLI command, and index folder still work as deprecated aliases. See **[Renamed from WP Loupe](docs/renamed-from-wp-loupe.md)** for details.

Quick Links
-----------

[](#quick-links)

[Requirements](#technical-requirements) | [Installation](#installation) | [REST API](#rest-api) | [AI Agent Integration](#ai-agent-integration-wordpress-abilities-api) | [Building Your Own Search UI](#building-your-own-search-ui) | [Settings](#settings) | [Reindexing](#reindexing) | [Filters](#filters) | [FAQ](#faq) | [Docs](docs/README.md) | [Changelog](CHANGELOG.md)

Overview
--------

[](#overview)

Loupe Search transforms WordPress's search functionality by:

- Creating a dedicated search index for lightning-fast results
- Supporting typo-tolerant searches
- Automatically maintaining the search index
- Providing a stable REST API for custom search experiences

> Integrating with AI agents or automation? Loupe Search registers native abilities via the [WordPress Abilities API](#ai-agent-integration-wordpress-abilities-api).

REST API
--------

[](#rest-api)

Loupe Search exposes search via REST endpoints:

- **POST** `/wp-json/loupe-search/v1/search` (recommended; supports JSON filters, facets, geo, explicit sorting, and search-result highlighting/snippets)
- **GET** `/wp-json/loupe-search/v1/search?q=...` (legacy; kept for backward compatibility)

> The old `wp-loupe/v1` namespace still works as a deprecated alias. See **[Renamed from WP Loupe](docs/renamed-from-wp-loupe.md)**.

Developer documentation (schema + examples + Gutenberg block example): **[docs/search-api.md](docs/search-api.md)**

AI Agent Integration (WordPress Abilities API)
----------------------------------------------

[](#ai-agent-integration-wordpress-abilities-api)

Loupe Search registers two abilities via the [WordPress Abilities API](https://developer.wordpress.org/apis/abilities-api/) (WordPress 6.9+) so AI agents and automation tools can discover and use search functionality natively — no extra configuration required:

- `loupe-search/search` — Typo-tolerant full-text search across indexed post types. Supports phrase matching, exclusion, and OR operators. Publicly accessible.
- `loupe-search/get-post` — Retrieve a single published post by ID. Publicly accessible.

Both abilities are discoverable through the standard WordPress Abilities registry and exposed via REST (`show_in_rest`).

> The legacy `wp-loupe/*` abilities (category `wp-loupe`) still work as deprecated aliases. See **[Renamed from WP Loupe](docs/renamed-from-wp-loupe.md)**.
>
> **Upgrading from the MCP server?** The experimental MCP server, token service, and WP-CLI token commands were removed in 0.8.5. See the **[MCP → Abilities API migration guide](docs/migration-mcp-to-abilities.md)**.

Features
--------

[](#features)

- Fast index-backed search for configured post types
- Typo-tolerance (Loupe)
- Per-field weighting, filterable fields, sortable fields (configured in Settings)
- Developer-facing REST API for building custom UIs, with filters, facets, geo search, and result highlighting/snippets
- Native AI agent integration via the WordPress Abilities API

Technical Requirements
----------------------

[](#technical-requirements)

- PHP 8.1 or higher
- SQLite 3.35+ (required by Loupe 0.13.x)
- PHP extensions: `pdo_sqlite`, `intl`, `mbstring`
- WordPress 6.9+

> **About the PHP extensions:** `pdo_sqlite` provides the SQLite driver Loupe uses to store and query the search index; `intl` powers locale-aware tokenizing, collation, and typo tolerance; and `mbstring` ensures multibyte (UTF-8) text is handled correctly during indexing and search. All three are required, but **they are enabled by default on most modern PHP installations and shared hosts**, so no action is usually needed. If your host is missing one, contact them or enable it in your PHP configuration.

Installation
------------

[](#installation)

1. **Install from WordPress.org**

    - In your WordPress admin, go to Plugins > Add New
    - Search for "Loupe Search"
    - Click "Install Now", then "Activate"
2. **Quick Install**

    - Download [`loupe-search.zip`](https://github.com/soderlind/loupe-search/releases/latest/download/loupe-search.zip)
    - Upload via WordPress Plugins > Add New > Upload Plugin
3. **Composer Install**

    ```
    composer require soderlind/loupe-search
    ```
4. **Post-Installation**

    - Activate the plugin
    - Go to Settings > Loupe Search
    - Click "Reindex" to build the initial search index (runs in batches; safe for large sites)

Building Your Own Search UI
---------------------------

[](#building-your-own-search-ui)

**Loupe Search works out of the box with WordPress’s standard search.**If your theme uses the normal search flow (e.g. a search form that routes to the built-in search results page), Loupe Search will power the results automatically — no custom UI required.

Loupe Search intentionally does **not** ship a front-end search block/shortcode UI. If you want a custom search experience (autocomplete, filters/facets, geo, custom sorting, etc.), build the UI you want and query Loupe Search via the REST API.

Start here: **[docs/search-api.md](docs/search-api.md)**

Settings
--------

[](#settings)

You can configure Loupe Search's search behavior and performance via the WordPress admin: Settings > Loupe Search.

### General Settings

[](#general-settings)

#### Post Types

[](#post-types)

Select which post types to include in the search index.

#### Field Weight

[](#field-weight)

Weight determines how important a field is in search results:

- Higher weight (e.g., 2.0) makes matches in this field more important in results ranking.
- Default weight is 1.0.
- Lower weight (e.g., 0.5) makes matches less important but still searchable.

#### Filterable Fields

[](#filterable-fields)

Filterable fields can be used to refine search results:

- Enable this option to allow filtering search results by this field's values.
- Best for fields with consistent, categorized values like taxonomies, status fields, or controlled metadata.
- Examples: categories, tags, post type, author, or custom taxonomies.

Note: Fields with highly variable or unique values (like content) make poor filters as each post would have its own filter value.

#### Sortable Fields

[](#sortable-fields)

Sortable fields can be used to order search results:

- Enable this option to allow sorting search results by this field's values
- Works best with numerical fields, dates, or short text values
- Examples: date, price, rating, title

### Advanced Settings

[](#advanced-settings)

Loupe Search provides advanced configuration options to fine-tune your search experience:

#### Prefix Search

[](#prefix-search)

- Configure prefix search behavior. Prefix search allows finding terms by typing only the beginning (e.g., "huck" finds "huckleberry").
- Prefix search is only performed on the last word in a search query. Prior words must be typed out fully to get accurate results. E.g. `my friend huck` would find documents containing huckleberry - `huck is my friend`, however, would not.

#### Typo Tolerance

[](#typo-tolerance)

- **Enable Typo Tolerance**: When enabled, searches will match terms with minor spelling errors.
- **First Character Double Counting**: When enabled, typos in the first character of a word will count as two errors instead of one.
- **Typo Tolerance for Prefix Search**: Allows typo tolerance in partial word searches.
- **Alphabet Size**: Define the size of the alphabet for typo calculations.
- **Index Length**: Configure the maximum length of indexed terms.
- **Typo Thresholds**: Set the minimum word length required for allowing different numbers of typos.

#### Query Parameters

[](#query-parameters)

- **Maximum Query Tokens**: Limits the number of words processed in a search query (default: 12).
- **Minimum Prefix Length**: Sets the minimum character length before prefix search activates (default: 3).

#### Languages

[](#languages)

- Configure which languages the search index should optimize for. Default is English ('en').

These advanced settings can be accessed in the WordPress admin under Settings > Loupe Search > Advanced tab.

Reindexing
----------

[](#reindexing)

Reindexing rebuilds the index for your configured post types.

- **Admin UI:** Settings → Loupe Search → click **Reindex** (runs in batches to avoid timeouts)
- **WP-CLI (recommended for large sites):**

    ```
     wp loupe-search reindex
    ```

    Optional flags:

    ```
     wp loupe-search reindex --post-types=post,page --batch-size=1000
    ```

Testing
-------

[](#testing)

- PHPUnit:

    ```
     composer test
    ```
- Pest (runs using the PHPUnit config):

    ```
     composer test:pest
    ```

FAQ
---

[](#faq)

### How does it handle updates to posts?

[](#how-does-it-handle-updates-to-posts)

The search index automatically updates when content is created, modified, or deleted.

### Will it slow down my site?

[](#will-it-slow-down-my-site)

No. Loupe Search uses a separate, optimized search index and doesn't impact your main database performance.

### Can I customize what content is searchable?

[](#can-i-customize-what-content-is-searchable)

Yes, using filters you can control exactly what content gets indexed and how it's searched.

### Does it work with custom post types?

[](#does-it-work-with-custom-post-types)

Yes, you can select which post types to include in the Settings page or via filters.

Filters
-------

[](#filters)

Eight filters let you change what gets indexed, how it is weighted, and how results are returned:

FilterUse it to`loupe_search_post_types`Choose which post types are indexed`loupe_search_index_protected`Index password-protected posts`loupe_search_db_path`Move the index directory`loupe_search_field_{$field_name}`Clean a core post field before indexing`loupe_search_schema_{$post_type}`Add/remove fields, set weights and sorting`loupe_search_is_safely_sortable_{$post_type}`Force a core field to be sortable`loupe_search_is_safely_sortable_meta_{$post_type}`Correct meta-field sortability detection`loupe_search_posts_per_page`Change results per page```
add_filter( 'loupe_search_post_types', function ( array $post_types ): array {
	$post_types[] = 'book';
	return $post_types;
} );
```

**[Filters reference →](docs/filters.md)** — signatures, defaults, schema options, recipes, and when to reindex.

> Filters use the `loupe_search_*` prefix; the old `wp_loupe_*` names still work as deprecated aliases. See **[Renamed from WP Loupe](docs/renamed-from-wp-loupe.md)**.

Acknowledgements
----------------

[](#acknowledgements)

- Loupe Search is built upon [Loupe](https://github.com/loupe-php/loupe/). Loupe is licensed under the MIT license.

Copyright and License
---------------------

[](#copyright-and-license)

Loupe Search is copyright © 2024 [Per Søderlind](http://github.com/soderlind).

Loupe Search is open-source software; you can redistribute it and/or modify it under the terms of the GNU General Public License, version 2, as published by the Free Software Foundation.

Loupe Search is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See [LICENSE](LICENSE) for more information.

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance100

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity39

Early-stage or recently created project

 Bus Factor1

Top contributor holds 87.1% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

3

Last Release

0d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/1649452?v=4)[Per Søderlind](/maintainers/soderlind)[@soderlind](https://github.com/soderlind)

---

Top Contributors

[![soderlind](https://avatars.githubusercontent.com/u/1649452?v=4)](https://github.com/soderlind "soderlind (392 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (35 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (17 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (6 commits)")

---

Tags

wordpress pluginsearch engineloupesearchingdeveloper-friendlytypo-tolerant

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/soderlind-loupe-search/health.svg)

```
[![Health](https://phpackages.com/badges/soderlind-loupe-search/health.svg)](https://phpackages.com/packages/soderlind-loupe-search)
```

###  Alternatives

[log1x/navi

A developer-friendly alternative to the WordPress NavWalker.

370700.3k12](/packages/log1x-navi)[contao/contao

Contao Open Source CMS development package

43114.4k2](/packages/contao-contao)[freemius/wordpress-sdk

Freemius WordPress SDK

307142.4k10](/packages/freemius-wordpress-sdk)[log1x/acf-editor-palette

A replica Gutenberg color picker field for Advanced Custom Fields.

101308.4k](/packages/log1x-acf-editor-palette)[neutron/sphinxsearch-api

SphinxSearch PHP API

56779.7k5](/packages/neutron-sphinxsearch-api)[jackpopp/geodistance

Search for locations within a radius using latitude and longitude values with your eloquent models.

126123.4k13](/packages/jackpopp-geodistance)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)