Download the PHP package silverstripe/silverstripe-discoverer-bifrost without Composer

🧭 Silverstripe Discoverer > Silverstripe Search

• Silverstripe Search
  • Purpose
  • Installation
  • Engine vs Index
  • Specify environment variables
  • Understanding your engine prefix and suffix:
  • Usage
  • Building a query
  • Processing results
  • Understanding fields and results

Purpose

Perform search queries on your Silverstripe Search data through Silverstripe CMS controllers.

This module is used to integrate with the 🌈 Bifröst - the API for Silverstripe's Search service.

Installation

Engine vs Index

[!IMPORTANT] TL;DR:\ For all intents and purposes, "engine" and "index" are synonomous. If we refer to something as "engine", but the Discoverer module is asking for an "index", then you simply need to give it the data you have for your engine.

The Discoverer module is built to be service agnostic; meaning, you can use it with any search provider, as long as there is an adaptor (like this module) for that service.

When Discoverer refers to an "index", it is talking about the data store used for housing your content. These data stores are known by different names across different search providers. Algolia and Elasticsearch call them "indexes", Typesense calls them "collections", App Search calls them "engines". Discoverer had to call them something in its code, and it chose to call then "indexes"; Silverstripe Search, however, calls them "engines".

Actions apply in the same way to all of the above. In Silverstripe Search, the action of "indexing" is the action of adding data to your engine, where it is said to be "indexed". Updating that data is commonly referred to as "re-indexing".

Specify environment variables

To integrate with Silverstripe Search, define environment variables containing your endpoint, engine prefix, and query API key.

Understanding your engine prefix and suffix:

[!IMPORTANT] TL;DR:

• All Silverstripe Search engine names follow a 4 slug format like this: search-<subscription>-<environment>-<suffix>
• Your <engine-prefix> is everything except -<suffix>; so, it's just search-<subscription>-<environment>

For example:

Why?

Because you probably have more than one environment type that you're running search on (e.g. Production and UAT), and (generally speaking) you should have different engines for each of those environments. So, you can't just hardcode the entire engine name into your project, because that code doesn't change between environments.

Whenever you make a query, Discoverer will ask you for the "index" name; you will actually want to provide only the <suffix>. We will then take BIFROST_ENGINE_PREFIX and your <suffix>, put them together, and that's what will be queried. This allows you to set BIFROST_ENGINE_PREFIX differently for each environment, while having your <suffix> hardcoded in your project.

More on this in Usage

Usage

As mentioned above, this module serves as an "adaptor provider" for Discoverer. Besides the installation steps above, you shouldn't really be interacting with this module in your code.

That said, below is a very simple examples on how to get your first query and results, but please see the documentation provided in Discoverer for more details on how to build queries and display results.

Building a query

Instantiate the search service:

Create a new query:

When performing a search, Discoverer will ask you for the Query object (above), and the "index" to be queried. This should just be the engine <suffix> (mentioned in Understanding your engine prefix and suffix):

Processing results

For this quick example, we'll assume we had a couple of fields in our engine: title, content (more on fields in Understanding fields and results)

You have your $results (a Results object). You can now loop through its Records, which is just a paginated list of Record.

In PHP:

Or in your template:

Understanding fields and results

The Discoverer module attempts to standardise all data store (index/engine/collection) fields into a "Silverstripe'y" format that we're all familiar with - PascalCase.

For example:

Note: Abbreviations like id, or url are treated like any other word, so even though it's quite common practice in Silverstripe to name it an ID (both capitalised), Discoverer will convert these to Id and Url respectively.

Why?

Because the Discoverer module has no way to programatically understand what abbreviation you might have in your code, so it's better to just use a standard across anything and everything that looks like a word.