# Hooks - Searchline 1.x documentation

> The actions, filters, REST routes and WP-CLI commands Searchline offers to developers.

Searchline's hooks let you change what is indexed, how searches are answered and ranked, what the live dropdown shows, and what the search report counts. Hooks marked "needs a reindex" change the index itself: run `wp searchline index` or click **Rebuild the index** on the Index tab after changing them.

## Actions

| Action | Arguments | When |
|---|---|---|
| `searchline_loaded` | none | On `plugins_loaded`, once Searchline is loaded (only while WooCommerce is active). Searchline's classes and the `SEARCHLINE_*` constants are available. |
| `searchline_settings` | `string $page`: the settings page slug, `searchline` | After Searchline's settings sections and fields are added to **WooCommerce → Searchline → Settings**. Add your own with `add_settings_section()` / `add_settings_field()` on that page, and register your options in the `searchline` settings group. |
| `searchline_store_api_request` | `WP_REST_Request $request`, `int[] $ids` | After Searchline rewrote a Store API products search (`/wc/store/v1/products?search=…`) to its results: `include` is set to `$ids`, `search` removed, and `orderby=include` unless the client asked for another order. |

```php
add_action( 'searchline_loaded', function () {
	// Searchline is active and ready.
} );
```

## Filters: what is indexed

| Filter | Arguments | What it changes |
|---|---|---|
| `searchline_post_types` | `string[] $types` | The post types in the index: those ticked under **Content types** that exist and are public. Needs a reindex. |
| `searchline_document` | `array<string,string> $fields`, `int $id`, `string $post_type` | The text indexed for a post, by field: `title`, `sku`, `category`, `tag`, `attribute`, `excerpt`, `content`, `meta`. Add text to a field to make it searchable with that field's weight; other keys are ignored. |
| `searchline_taxonomy_field` | `string $field`, `string $taxonomy` | Which field a taxonomy's terms are indexed in: `category`, `tag`, `attribute`, or `''` for none. By default categories and brands go in `category`, tags in `tag` and `pa_*` attributes in `attribute`. |
| `searchline_detected_fields` | `array<string,string> $fields` (meta key => label) | The custom fields offered as checkboxes on the Settings tab (from ACF, Meta Box and Pods). |
| `searchline_stopwords` | `string[] $words` | Words neither indexed nor searched (English sites: "the", "and", "with"…; none otherwise). Needs a reindex. |
| `searchline_english` | `bool $english` | Whether content is treated as English: stemming ("boots" finds "boot") and English stopwords. Defaults to true when the site's locale starts with `en`. Needs a reindex. |
| `searchline_batch_size` | `int $size` (default 250, at least 10) | How many posts each batch of an index build reads and writes. |
| `searchline_optimize_after_build` | `bool $optimize` (default true) | Whether the index's main table is optimized after a full build, which makes it smaller. |

```php
// Index a product's "_material" custom field with the attribute weight.
add_filter( 'searchline_document', function ( $fields, $id, $post_type ) {
	if ( 'product' === $post_type ) {
		$fields['attribute'] .= ' ' . get_post_meta( $id, '_material', true );
	}
	return $fields;
}, 10, 3 );
```

## Filters: searching and ranking

| Filter | Arguments | What it changes |
|---|---|---|
| `searchline_query_types` | `string[]\|null $types`, `WP_Query $query` | The post types Searchline answers a `WP_Query` for. Return `null` to leave the query to WordPress. |
| `searchline_results` | `int[] $ids`, `string $query`, `string[] $types` | The post IDs found for a search, best first, before access rules and `WP_Query`'s own filters. |
| `searchline_synonyms` | `array $rules`: each `['from' => string[], 'to' => string[][]]` | The synonym rules from the Synonyms tab: each `from` word list also finds every word list in `to`. Words are lowercase without accents. |
| `searchline_typo_ratio` | `int $ratio` (default 10) | How much more common a typo match must be than the search word, when the search word is itself in the index. |
| `searchline_prefix_limit` | `int $limit` (default 30) | How many words starting with the last search word are matched, most common first. 0 turns prefix matching off. |
| `searchline_candidate_cap` | `int $cap` (default 5000) | At most how many documents holding a search's rarest word are scored. Never below the **Find at most … results per search** setting. |
| `searchline_redirect` | `string $url`, `string $search` | Where a search redirects to. Return `''` to show the results. |
| `searchline_redirect_label` | `string $label`, `string $url` | The name shown for a redirect: in the dropdown's "Go to …" row when a redirected search has no results, on the Redirects tab and in the search report's Status column. By default, the title of the page, post or product, otherwise the address. |

```php
// Never answer searches for the "faq" post type.
add_filter( 'searchline_query_types', function ( $types, $query ) {
	return is_array( $types ) && in_array( 'faq', $types, true ) ? null : $types;
}, 10, 2 );
```

A `WP_Query` can also opt out with the query arg `'searchline' => false`. Searchline leaves admin, REST (other than the Store API's product search) and WP-CLI queries alone; `'searchline' => true` makes it answer such a query anyway.

## Filters: the live dropdown

| Filter | Arguments | What it changes |
|---|---|---|
| `searchline_live_results` | `array $out`, `string $term`, `bool $products_only` | The dropdown's whole answer: `term`, `redirect`, `suggestion`, `total`, `products`, `posts`, `more` (the "See all" address). `$products_only` is true for a product search form. |
| `searchline_live_product` | `array $row`, `WC_Product $product`, `string $term` | One product row: `id`, `type`, `title`, `url`, `image`, `price` (HTML), `stock` (HTML), `sku`, `badges`, `cart` (whether it can be added from the dropdown), `cart_label`. |
| `searchline_live_badges` | `string[] $badges`, `WC_Product $product` | The plain-text badges on a product row: Labelline's labels when it is active, otherwise "Sale" for products on sale. |
| `searchline_live_cache` | `bool $cache`, `string $term` | Whether result IDs are cached for two minutes for this request. Default: only for logged-out visitors on sites with a persistent object cache; never in the database. Turn it off when what logged-out visitors may see varies. |
| `searchline_live_config` | `array $config` | The dropdown script's settings and texts (`window.searchlineLive`): REST addresses, `minChars`, `all` (every search form), `delay` (ms), `i18n`. |
| `searchline_client_ip` | `string $ip` | The visitor's IP address for the live search limit. Behind a proxy or CDN, return the address it forwards. It is never stored. |
| `searchline_rate_limit_applies` | `bool $applies` (default true) | Whether the live search limit applies to this request, for example false for a monitoring service. |

```php
// Behind Cloudflare: use the visitor's real address for the live search limit.
add_filter( 'searchline_client_ip', function ( $ip ) {
	return isset( $_SERVER['HTTP_CF_CONNECTING_IP'] ) ? sanitize_text_field( wp_unslash( $_SERVER['HTTP_CF_CONNECTING_IP'] ) ) : $ip;
} );
```

## Filters: the search report

| Filter | Arguments | What it changes |
|---|---|---|
| `searchline_log_search` | `bool $count` (false for crawlers), `string $term` | Whether a search (or a click on its results) is counted in the report. |
| `searchline_term_is_private` | `bool $private`, `string $term` | Whether a term is kept out of the report as personal data. By default: email addresses and runs of 8 or more digits. |

## REST API

Both routes are public, like the search itself, and limited per visitor (429 "Too many searches" over the limit).

| Route | What it does |
|---|---|
| `GET /wp-json/searchline/v1/live?q=…&products=1` | The dropdown's answer for a search (see `searchline_live_results`). `products=1` searches products only. 404 while the dropdown is off. |
| `POST /wp-json/searchline/v1/track` | Counts a search or a click in the report: `term`, `event` (`search` or `click`), `products`. |

## WP-CLI

`wp searchline index` (build the whole index now), `wp searchline status`, `wp searchline search <search> [--type=<type>]` (results before access rules) and `wp searchline clear`. See [The index](the-index).

## Constants

`SEARCHLINE_VERSION`, `SEARCHLINE_FILE`, `SEARCHLINE_URL` and `SEARCHLINE_DIR`.

Source: https://extendiment.com/plugins/searchline/docs/1.x/hooks