Download the PHP package studioespresso/craft-scout without Composer

Scout for Craft CMS

Craft Scout provides a simple solution for adding full-text search to your entries. Scout will automatically keep your search indices in sync with your entries.

Requirements

This plugin requires Craft CMS 4.x or later and PHP 8.0.2 or later.

Installation

Open your terminal and go to your Craft project:

Setup

To define your indices, copy the scout.php file to your config folder.

Example Index Configuration

->elementType(string $class)

The element type that this index contains, by default Scout uses craft\elements\Entry::class

Craft's default element type classes are:

• craft\elements\Asset
• craft\elements\Entry
• craft\elements\User

->criteria(callable $query)

This function accepts an ElementQuery and should also return an ElementQuery

->transformer(callable|string|array|TransformerAbstract $transformer)

The transformer that should be used to define the data that should be sent to Algolia for each element. If you don’t set this, the default transformer will be used, which includes all of the element’s direct attribute values, but no custom field values.

Your custom transformer class would look something like this:

->splitElementsOn(array $keys)

For long documents it is advised to divide the element into multiple rows to keep each row within row data size. This can be done using splitElementsOn().

Make sure to return an array in your transformer for these keys.

Important - distinctID (available after indexing) must be set up as an attribute for faceting for deletion of objects to work when using splitElementsOn.

->indexSettings(IndexSettings $settings)

You can use this to define index settings that get synced when you call the ./craft scout/settings/update console command. This way you can keep your index settings in source control. The IndexSettings object provides autocompletion for all Algolia's settings

[!NOTE]
Note that settings are not synced automatically, but only when the ./craft scout/settings/update console command is run.

Replicas

Replicas can be created with the replicas function on IndexSettings. To configure replicas, include them in the indices array and set their replicaIndex to true so that they are not included in any syncing operations.

Replica indices can have their configuration updated using the ./craft scout/settings/update console command.

Twig variables

You can access the Algolia settings set in your config file through the following Twig variables.

Console commands

Scout provides two easy console commands for managing your indices.

Importing

To import one or all indices you can run the following console command

The indexName argument is not required, all your mappings will be imported when you omit it.

Flushing/Clearing

Clearing an index is as easy as running a command in your console.

As with the import command, indexName is not required.

When flushing, Scout will ask you to confirm that you really want to clear all the data in your index. You can bypass the confirmation by appending a --force flag.

Refreshing

Does a flush/clear first and then imports the index again.

Skipping an Element

You can omit an element from being indexed by returning an empty array from the transform method:

Events

ShouldBeSearchableEvent

This event allows you to customize which elements or element types get checked on save (or more specifically, every time the SearchableBehaviour is triggered).

The event has a properties:

• $element (the element being saved)
• $shouldBeSearchable (wether or not the element should be searchable, defaults to true)

An example use-case for this would be to check the type of the element that's being saved and settings shouldBeSearchable to false when it's a Matrix block.

AfterIndexImport

This event runs at the end of the ImportIndex job, when every item has been processed.

The event has one property:

• $indexName (the name of the index that just finished importing

An example use-case for this would be to keep a log or dateLastImported if you're running imports on a schedule.

Upgrading from 1.x

The configuration has changed from how Scout v1 did its configuration. Please see the setup section below on how to configure Scout.

The following changes are the most notable:

• The mappings configuration key has been changed to indices and there is a new way to configure the indices
• The criteria is now a callable that returns an ElementQuery. Every Index should define a siteId in the criteria, otherwise the primary site is chosen.
• New queue and batch options added to the settings
• Old confuguration keys on the mappings have been replaced by functions on the rias\scout\ScoutIndex object.

Brought to you by Studio Espresso and Rias