Skip to main content

InstantSearch for WP

This documentation covers the Yoko Core integration with the InstantSearch for WP plugin, implemented in includes/Integrations/InstantSearchForWP.php.

Overview​

When the InstantSearch for WP plugin is active, Yoko Core augments indexed Algolia records with Content Gating metadata so protected content can still participate in faceted search without exposing access-control details in search responses.

The integration is loaded conditionally from includes/Integrations.php only when the INSTANTSEARCH_FOR_WP_VERSION constant is available.

Integration File​

File: includes/Integrations/InstantSearchForWP.php

What it does​

  • Adds a content_protection_roles attribute to indexed records.
  • Uses the parent post's Content Gating settings for attachments and PDFs.
  • Excludes content_protection_roles from returned search result attributes.
  • Keeps content_protection_roles facetable, but removes it from searchable attributes.
  • Flags restricted records to use excerpt content in search results.

Indexed Attribute​

The integration adds a content_protection_roles array to each indexed record.

  • The value is sourced from the content_restriction_allowed_roles post meta used by Yoko Content Gating.
  • Role values are normalized with sanitize_key() before indexing.
  • The attribute is added as a facet so front-end implementations can filter by access role when needed.

Attachments and PDFs​

If the indexed object is an attachment and has a parent post, Yoko Core reads the Content Gating roles from the parent post instead of the attachment itself. This is important for PDF indexing workflows where the attachment inherits access rules from the content item that references it.

Related docs:

Searchability Behavior​

The content_protection_roles field is intentionally not used as a searchable attribute.

Yoko Core modifies the InstantSearch index settings so that:

  • content_protection_roles is removed from searchableAttributes
  • content_protection_roles remains in attributesForFaceting
  • the facet is rewritten as filterOnly(content_protection_roles)

This allows access-related filtering without affecting keyword matching, result ranking, or accidental search matches on role slugs.

Search Result Payload Behavior​

Yoko Core also excludes content_protection_roles from the attributes returned in normal search hits.

This means the field is still available for Algolia filtering and faceting, but is not included in the public hit payload by default.

Restricted Content Results​

When a record has one or more allowed roles, Yoko Core marks it as excerpt-driven for result rendering.

Behavior​

  • Sets showExcerptInSearchResults to true
  • Replaces the result content field with excerpt text when possible
  • Preserves a dedicated excerpt field on the indexed record

Excerpt fallback order​

  1. Existing excerpt value already present on the record
  2. The effective post excerpt
  3. A generated fallback excerpt based on trimmed content

For attachments and PDFs, the effective post is the parent post when one exists.

This works well with gated content because search results can still show a teaser without indexing or exposing the full restricted body in the visible result field.

Hook Reference​

The integration currently hooks into these InstantSearch for WP filters:

  • instantsearch_algolia_record
  • instantsearch_facet_attributes
  • instantsearch_attributes_to_retrieve_exclude
  • instantsearch_index_settings

These hooks let Yoko Core alter indexed records and Algolia settings without changing the InstantSearch for WP plugin directly.

Expected Use Case​

This integration is intended for sites that need all of the following:

  • InstantSearch for WP for Algolia-based search
  • Yoko Content Gating for role-based access control
  • gated content or gated PDFs to appear in search with teaser-style results

If your project needs custom front-end filtering based on access roles, use the indexed content_protection_roles facet in your InstantSearch configuration rather than making the attribute searchable.