Laravel Full-Text Search

Laravel Scout (opens new window) is a powerful package that provides a simple, driver-based solution for adding full-text search to Laravel Eloquent (opens new window) ORM models.

Laravel Scout has native support for Typesense and this guide will focus on how to add the Laravel Scout Typesense Driver to an existing Laravel project in order to add full-text search to your Laravel application.

Prerequisites

This guide will use Laravel Sail (opens new window), a CLI that enables you to run Laravel applications using Docker.

Please ensure that you have Docker installed on your machine before proceeding. You can install Docker by following the instructions on the official Docker website (opens new window).

To create a new Laravel project using Laravel Sail, you can follow the instructions in the official Laravel documentation (opens new window).

This guide will use a Linux environment, but you can adapt the commands to your operating system.

Step 1: Create a New Laravel Project Using Laravel Sail

Laravel Sail by default uses a set of default services (opens new window), if the user doesn't specify any specific services. For this guide, we will use the PostgreSQL database service. This command is used to create a new Laravel project using Laravel Sail:

This command will create a new Laravel project named typesense-scout-example with the PostgreSQL service enabled. You can then navigate to the project directory:

Start the Laravel Sail Docker containers:

And apply the User model migrations:

You can now access the Laravel application by visiting http://localhost in your browser.

Step 2: Install the Laravel Scout Typesense Driver

To install the Laravel Scout Typesense Driver, let's add the package to your Laravel project. You can do this by running the following command:

And then selecting the typesense driver from the list.

NOTE: The default Typesense in Laravel Scout version is 0.25.2. If you want to use the latest version, you can specify it in the docker-compose.yml file. For example, to use version 26.0, you can add the following line to the docker-compose.yml file:

In order for the changes to take effect, let's rebuild the Docker containers:

Step 3: Install and Configure Laravel Scout

As per Laravel Sail's documentation (opens new window), to install Laravel Scout via Composer, let's run the following command:

You'll also need to install the Official PHP client for the Typesense API (opens new window) by running the following command:

Next, let's publish the Laravel Scout configuration file:

And configure Laravel Scout to use the Typesense driver by modifying the config/scout.php file:

Configure Queueing (Optional)

While not required, you can configure Laravel Scout to handle indexing and searching using queues (opens new window). For this guide, we'll use the database queue driver, but you can use a plethora of different drivers mentioned in the official Laravel documentation (opens new window). To configure the database queue driver, let's ensure that the database includes a table for the jobs by running the following commands:

Next, let's configure the SCOUT_CONNECTION environment variable in the .env file to use the database queue driver:

And finally, let's configure the config/scout.php file to use the database queue driver:

You can then run the queue worker to start processing the queued jobs:

This will start the queue worker in the background, processing the queued jobs. For more info regarding queue workers and their benefits, you can refer to the official Laravel documentation (opens new window).

Step 4: Create a Model and Migrate Data

Next, let's add some data to the PostgreSQL database. You can use any dataset you want, but this guide will use Terenci Claramunt's (@terencicp (opens new window)) public dataset of Steam Games released from 2013 to 2023, which you can find here (opens new window), and save it in the data folder. To use it, you'll have to create an Eloquent model for the Steam Games, and create a migration file, along with a model file and a controller. To do so, let's use the following command:

This command will create a new Eloquent model named Game, along with a migration file and a resource controller. Let's now modify the model file app/Models/Game.php to include the necessary columns for the Steam Games dataset:

And modify the migration file database/migrations/**timestamp**_create_games_table.php to include the necessary columns for the Steam Games dataset:

You can then run the migration to create the games table in the PostgreSQL database:

We've created a simple bash script (opens new window) to load all the data into the PostgreSQL database. You can add the script in the scripts folder and run it in the terminal to populate the games table with the Steam Games dataset.

Step 5: Index the Data Using Laravel Scout

To index the data using Laravel Scout, let's add the Searchable trait to the Game model, and create a toSearchableArray method that returns the indexable data array for the model. This is required only for Models that have a different schema in the database than in Typesense, e.g. Models that include Dates. You can modify the app/Models/Game.php file as follows:

And then define the Collection Schema in the config/scout.php file:

After setting up the Laravel Scout Driver, all subsequent model changes will be automatically synced with Typesense, using the Model Observer (opens new window) provided by Laravel Scout.

To verify that it's working, let's create a new record in the Games table. We'll be using Laravel Tinker (opens new window), a REPL enabling us to write and execute PHP code interactively. You can run the following command to open Laravel Tinker:

And then create a new record in the Games table:

You can then run a search query to verify that the record has been indexed in Typesense:

You should see the record you created in the search results.

Dynamic Search Parameters

You can also set search parameters for searching through your collections on the fly. For example, you can set the query_by parameter to search by a game's Steam App ID only:

Step 6: Backfill Existing Data

Our setup so far will cause data changes to be auto-synced into Typesense for any changes going forward.

To backfill your existing data in your tables into Typesense, you can run this command:

To test that everything is working correctly, you can run a search query:

You can then proceed as you prefer. You can create a controller to handle the search requests, or use the Typesense InstantSearch Adapter (opens new window) to use Instantsearch.js on your frontend. If you prefer using a Javascript framework, you can use Inertia.js (opens new window) to create a Vue.js, Svelte or React.js frontend.

Examples

This Demo Laravel app (opens new window) uses a React Typescript frontend with the Typesense InstantSearch Adapter, and uses Laravel Scout to sync the data from Postgres to Typesense.