When you're building APIs, one key feature that often gets overlooked is search. So how do you handle search efficiently in your Laravel app? That's what we’ll explore today using TypeSense, a powerful open-source search engine.

Why TypeSense?

There are plenty of third-party options available like Algolia or search engines like ElasticSearch, but TypeSense offers:

• Real-time search results.
• Fast indexing.
• Simplicity in setup for developers.

You can start your search service locally and have full control over how data is indexed and queried. Let’s break down how to integrate TypeSense into your Laravel application using Laravel 11.

Step 1: Install Scout and TypeSense

Before jumping into coding, we need to get the tools set up. First, we’ll use Laravel Scout to handle the search indexing. Laravel Scout provides a great abstraction over various search services, including TypeSense.

Install Scout:

composer require laravel/scout

Publish Scout Configuration:

php artisan vendor:publish --provider="Laravel\Scout\ScoutServiceProvider"

Install the TypeSense SDK:

composer require typesense/typesense-php

You can find more about the SDK here.

Configure Scout to use TypeSense by adding this to your .env file:

SCOUT_DRIVER=typesense

Step 2: Define Your Search Schema

Now that you have everything installed, the next step is to define what data should be indexed. In Laravel, we do this by marking a model as "searchable" and defining the fields that will be used in search queries.

Here's an example for a Car model:

use Laravel\Scout\Searchable;

class Car extends Model
{
    use Searchable;

    public function toSearchableArray(): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'model' => $this->model,
            'year' => $this->year,
            'created_at' => $this->created_at,
        ];
    }
}

Step 3: Set Up TypeSense Index

For the search to work, you need to set up a schema in TypeSense. The schema defines what fields are searchable and their data types.

Here’s how you can define the schema:

$client = new \Typesense\Client([
    'api_key' => env('TYPESENSE_API_KEY'),
    'nodes' => [
        [
            'host' => 'localhost',
            'port' => '8108',
            'protocol' => 'http',
        ]
    ]
]);

$client->collections->create([
    'name' => 'cars',
    'fields' => [
        ['name' => 'id', 'type' => 'string'],
        ['name' => 'name', 'type' => 'string'],
        ['name' => 'model', 'type' => 'string'],
        ['name' => 'year', 'type' => 'int32'],
        ['name' => 'created_at', 'type' => 'int64'],
    ]
]);

In the example above, we’re defining fields for a car: id, name, model, year, and created_at. You can adapt this for any other types of entities you need to search for.

Step 4: Implement the Search Logic

Once the schema and data are indexed, the next step is to query TypeSense for search results. Here's an example where we allow users to search cars by name and model:

use App\Models\Car;

Route::get('/cars', function (Request $request) {
    $searchTerm = $request->query('q');
    $cars = Car::search($searchTerm)->get();

    return response()->json($cars);
});

This route listens for GET requests on /cars, searches the Car model for the query term, and returns the results as JSON.

Step 5: Catch Unsuccessful Search Queries

Not every search will return results. Knowing what users are searching for can help you improve your API by adding more data or understanding user behavior. For this, we’ll log unsuccessful queries.

Here’s how to create middleware to log search queries:

php artisan make:middleware SearchLog

In your SearchLog middleware:

public function handle(Request $request, Closure $next)
{
    $response = $next($request);

    $searchTerm = $request->query('q');
    if ($response->getData()->isEmpty()) {
        Log::info("Search term not found: {$searchTerm}");
    }

    return $response;
}

Don’t forget to register the middleware in your Kernel.php.

Step 6: Monitor Searches with TypeSense Analytics

TypeSense offers built-in analytics to help you monitor how your search performs and what users are looking for. You can read more about TypeSense Analytics here.

Step 7: Building a Search Interface

A great search API is one thing, but if your users can’t interact with it properly, it’s useless. You can integrate this into your frontend with JavaScript, Vue.js, or React.js. TypeSense has a TypeSense InstantSearch plugin that you can use with Vue.js or React.js.