Scout Extended: The Full Power of Algolia in Laravel

We are thrilled to announce the release of Scout Extended — the official Algolia Laravel integration. Built on top of the latest release of Laravel Scout, Scout Extended lets you take advantage of all of Scout’s great features, and, at the same time, leverage the complete Algolia’s search experience.

When Laravel Scout was first released, it provided immediate access to Algolia search. For many, this meant simply getting fast and typo-tolerant search out of the box. However, Algolia is way more than speed and typo tolerance. On par with speed, there’s also relevance — having the best matching records always appear at the top of your results. To achieve this, you’ll need to set up a few basics. Scout Extended gives you direct access to these and other settings through Laravel Artisan Commands.

Easier access to configuring Algolia is only one of the extensions we’ve added on top of Laravel Scout. Another feature of equal importance is support for aggregators: now you can centralize your search, creating a single point of entry for your entire website. Other improvements include full reindexing without any downtime for your users, extending the search builder, getting status overviews, and many other features. Let’s get into some of the details.

If you prefer to watch vs. read, here is a talk I recently gave on Scout Extended.

Aggregators — multiple models in one index

An aggregator is a clean way to implement site-wide search among multiple models. In other words, it allows you to have multiple models in one index.

To create a new aggregator, use the scout:make-aggregator Artisan command. This command will create a new aggregator class in the app/Search directory:

php artisan scout:make-aggregator News

After generating your aggregator, you should fill the $models property of the class, which will be used to identify the models that should be aggregated:

	<?php

	namespace App\Search;

	use Algolia\ScoutExtended\Searchable\Aggregator;

	class News extends Aggregator
	{
	/**
	* The names of the models that should be aggregated.
	*
	* @var string[]
	*/
	protected $models = [
	\App\Event::class,
	\App\Article::class,
	];
	}

view raw News.php hosted with ❤ by GitHub

An aggregator is a standard searchable class, and, as usual, you may begin searching on the aggregator using the search method or the raw method:

	<?php

	$models = App\Search\News::search('Star Trek')->get();
	echo get_class($models[0]); // "App\Article"
	echo get_class($models[1]); // "App\Comment"

	$results = App\Search\News::search('Star Trek')->raw();
	/*
	{
	"hits":[
	{
	"id":1,
	"title": "Article title",
	"slug": "article-title",
	"content": "Article content",
	"objectID":"App\\Article::1",
	...
	},
	{
	"id": 1,
	"content": "Comment content",
	"objectID": "App\\Comment::1",
	...
	},
	],
	...
	}
	*/

view raw searching_aggregators.php hosted with ❤ by GitHub

To learn more about Aggregators in Scout Extended, please review the Scout Extended Documentation.

Zero downtime reimports — painless to deploy

With Scout Extended, it’s a breeze to import data in production. To keep your existing search experience available while reimporting your data, use the scout:reimport Artisan command:

php artisan scout:reimport

This Artisan command will output the following content:

To ensure that searches performed on the index during the rebuild will not be interrupted, Scout Extended uses a temporary index to import all records before moving the temporary index to the production index. We have you covered.

Configuring Algolia from within Laravel

You’ll start with the scout:optimize Artisan command, to optimize the search experience based on information from the searchable class:

php artisan scout:optimize

This might be sufficient. scout:optimize does its best to generate the settings of your searchable class index, but you may need to edit those settings in config/scout-articles.php. For example, two of the most important configurations to get right are searchable attributes and custom ranking:

	<?php

	return [

	/*
	\|--------------------------------------------------------------------------
	\| Searchable Attributes
	\|--------------------------------------------------------------------------
	\|
	\| Limits the scope of a search to the attributes listed in this setting. Defining
	\| specific attributes as searchable is critical for relevance because it gives
	\| you direct control over what information the search engine should look at.
	\|
	\| Example: ["name", "email", "unordered(city)"]
	\|
	*/

	'searchableAttributes' => ['subject', 'body', 'slug', 'author_name', 'author_email'],

	/*
	\|--------------------------------------------------------------------------
	\| Custom Ranking
	\|--------------------------------------------------------------------------
	\|
	\| Custom Ranking is about leveraging business metrics to rank search
	\| results - it's crucial for any successful search experience. Make sure that
	\| only "numeric" attributes are used, such as the number of sales or views.
	\|
	\| Examples: ['desc(comments_count)', 'desc(views_count)']
	\|
	*/

	'customRanking' => ['asc(sales_count)', 'desc(views_count)', 'desc(created_at)'],

	// ...
	];

view raw scout_extended_settings_file.php hosted with ❤ by GitHub

Once you have verified the settings file, all you need to do is synchronize the settings with Algolia using the scout:sync Artisan command:

php artisan scout:sync

You may also edit settings using the Algolia Dashboard. However, make sure you apply those settings locally running the scout:sync Artisan command.

An improved search builder

Scout Extended pushes the Laravel Scout’s search builder to the next level, adding new methods and improving the existing ones. Here are some examples.

where

The where method may be used to compare a field’s value against another value. With Scout Extended, this method shares the same API of the Laravel Query Builder, allowing you to filter results either via a comparison or a range numerically:

	<?php

	$articles = Article::search('Star Trek')->where('views', '>', 100)->get();
	$articles = Article::search('Star Trek')->where('created_at', '>=', now()->subDays(7))->get();
	$articles = Article::search('Star Trek')->where('views', 100)->get(); // views = 100

view raw scout_extended_where.php hosted with ❤ by GitHub

The supported operators are: <, <=, =, !=, >=, >.

whereBetween

The whereBetween method verifies that a field’s value is between two values:

	<?php

	$products = Products::search('Star Trek')
	->whereBetween('price', [100, 200])
	->get();

view raw scout_extended_where_between.php hosted with ❤ by GitHub

You can do the same with whereIn, with, count, and aroundLatLng. Head over to Scout Extended Documentation to find out more about this.

Status overviews

Scout Extended provides a beautiful overview of your application indexes, allowing you to easily monitor the number of records, among other key metrics.

To get an overview of your application indexes, use the scout:status Artisan command:

php artisan scout:status

This Artisan command will output a table with the following content:

And more!

Automatic transformation of data before being send to Algolia.
Easy integration with InstantSearch libraries.
Access API directly using Algolia’s Facade.
Need to split large records? Use Splitters.

Scout Extended is 100% open source, so you’re free to dig through the source code to see exactly how it works. Dig right in! Visit the Scout Extended documentation.

See something that needs to be improved? Just send us a pull request on GitHub.

Thanks, we hope you enjoy this new release!

ABOUT THE AUTHOR