Membangun fitur pencarian yang cepat dan relevan sering kali lebih rumit daripada sekadar menambahkan query LIKE ke database. Saat data mulai bertambah, kebutuhan seperti typo tolerance, ranking hasil, filtering, dan performa responsif menjadi sulit ditangani hanya dengan query SQL biasa. Di sinilah Algolia sering digunakan sebagai layanan mesin pencari terkelola, dan Laravel Scout membantu menghubungkannya dengan aplikasi Laravel secara lebih sederhana.

Panduan ini ditujukan untuk pemula yang ingin memahami integrasi dasar Algolia dengan Laravel Scout. Kita akan membahas apa itu Algolia, kapan cocok dipakai, cara membuat akun dan API key, memilih key yang aman untuk backend dan frontend, instalasi package yang diperlukan, konfigurasi, proses indexing awal, hingga contoh pencarian sederhana dan troubleshooting umum.

Apa Itu Algolia dan Kapan Cocok Dipakai?

Algolia adalah layanan pencarian terkelola yang dirancang untuk memberikan hasil pencarian cepat, relevan, dan kaya fitur. Alih-alih menjalankan pencarian langsung ke database utama aplikasi, data yang ingin dicari akan dikirim ke index Algolia. Aplikasi Anda kemudian melakukan query ke index tersebut saat pengguna melakukan pencarian.

Keunggulan utama pendekatan ini adalah:

  • Performa pencarian tinggi, terutama untuk aplikasi dengan banyak data.
  • Relevansi hasil yang lebih baik, termasuk typo tolerance dan ranking.
  • Fitur pencarian lanjutan seperti highlighting, faceting, filtering, dan sorting tertentu.
  • Pemisahan beban dari database utama aplikasi.

Algolia cocok dipakai ketika:

  • Anda memiliki katalog produk, artikel, dokumentasi, atau daftar konten yang terus bertambah.
  • Pengalaman pencarian adalah fitur penting di aplikasi.
  • Query SQL biasa mulai terasa lambat atau sulit dipelihara.
  • Anda membutuhkan fitur pencarian modern tanpa membangun mesin pencari sendiri.

Namun ada juga trade-off yang perlu dipahami:

  • Biaya tambahan karena Algolia adalah layanan eksternal.
  • Sinkronisasi data harus dikelola dengan benar agar index tidak ketinggalan.
  • Ketergantungan pada layanan pihak ketiga.

Jika kebutuhan pencarian Anda masih sangat sederhana dan dataset kecil, query database biasa mungkin masih cukup. Algolia lebih terasa manfaatnya ketika kualitas dan performa pencarian menjadi kebutuhan nyata.

Membuat Akun Algolia, Application, dan API Key

1. Membuat akun Algolia

Langkah awalnya adalah membuat akun di dashboard Algolia. Setelah login, Anda akan mendapatkan sebuah application. Dalam konteks Algolia, application adalah wadah utama untuk index, pengaturan pencarian, dan API key.

2. Menemukan Application ID dan API Key

Di dashboard Algolia, Anda biasanya akan melihat beberapa kredensial penting:

  • Application ID
  • Search-Only API Key
  • Admin API Key

Secara umum, peran masing-masing seperti ini:

  • Admin API Key: digunakan untuk operasi penuh seperti menulis, menghapus, dan mengelola index. Key ini hanya boleh digunakan di server/backend.
  • Search-Only API Key: digunakan untuk operasi pencarian saja. Key ini relatif aman dipakai di frontend karena tidak memiliki hak tulis.

3. Memilih key yang aman untuk server dan frontend

Ini penting karena salah penggunaan key bisa menjadi celah keamanan:

  • Untuk Laravel backend, gunakan Admin API Key atau key lain yang memiliki izin indexing yang diperlukan.
  • Untuk frontend/browser, gunakan Search-Only API Key.
  • Jangan pernah mengirim Admin API Key ke JavaScript frontend, mobile app, atau repositori publik.

Jika perlu, Anda juga dapat membuat API key dengan hak akses yang lebih terbatas dari dashboard Algolia, misalnya key khusus index tertentu atau key dengan pembatasan operasi tertentu.

Instalasi Laravel Scout dan Client Algolia

Laravel Scout berfungsi sebagai lapisan integrasi antara model Eloquent dan search driver seperti Algolia. Untuk mulai menggunakannya, instal Scout dan client Algolia terbaru yang didukung.

composer require laravel/scout algolia/algoliasearch-client-php

Setelah itu, publikasikan file konfigurasi Scout:

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

Perintah ini akan membuat file config/scout.php agar Anda dapat mengatur driver dan perilaku indexing.

Konfigurasi file .env

Tambahkan konfigurasi berikut ke file .env:

SCOUT_DRIVER=algolia
ALGOLIA_APP_ID=YourAlgoliaAppId
ALGOLIA_SECRET=YourAlgoliaAdminApiKey

Di banyak setup Laravel Scout, nama variabel yang digunakan untuk API key Algolia adalah ALGOLIA_SECRET. Pastikan nama variabel ini sesuai dengan isi file config/scout.php di proyek Anda, karena implementasi dapat sedikit berbeda tergantung versi package dan publikasi config.

Memeriksa config/scout.php

Pastikan driver dan kredensial diarahkan ke environment variable yang benar:

'driver' => env('SCOUT_DRIVER', 'algolia'),

'algolia' => [
    'id' => env('ALGOLIA_APP_ID', ''),
    'secret' => env('ALGOLIA_SECRET', ''),
],

Jika Anda mengubah file .env tetapi aplikasi masih membaca nilai lama, jalankan:

php artisan config:clear
php artisan cache:clear

Ini penting karena salah satu masalah paling umum adalah konfigurasi sudah diubah tetapi masih tersimpan dalam cache aplikasi.

Menambahkan Searchable pada Model

Setelah Scout terpasang, langkah berikutnya adalah menandai model yang ingin di-index menggunakan trait Searchable. Misalnya kita ingin membuat model Post bisa dicari.

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;

class Post extends Model
{
    use Searchable;

    protected $fillable = [
        'title',
        'slug',
        'content',
        'status',
    ];

    public function toSearchableArray(): array
    {
        return [
            'id' => $this->id,
            'title' => $this->title,
            'slug' => $this->slug,
            'content' => $this->content,
            'status' => $this->status,
        ];
    }
}

Trait Searchable memberi kemampuan pada model untuk disinkronkan ke search engine. Saat model dibuat, diubah, atau dihapus, Scout dapat meneruskan perubahan tersebut ke Algolia.

Mengapa toSearchableArray penting?

Method toSearchableArray() menentukan data apa saja yang akan dikirim ke index Algolia. Anda tidak harus mengirim seluruh kolom tabel. Bahkan, lebih baik hanya mengirim field yang memang diperlukan untuk pencarian.

Manfaatnya:

  • Mengurangi ukuran record di index.
  • Mengontrol data sensitif agar tidak ikut terindeks.
  • Meningkatkan relevansi karena hanya field penting yang dipakai.

Contoh kesalahan umum adalah mengirim seluruh atribut model tanpa filter, lalu tanpa sadar ikut mengirim field internal yang tidak seharusnya muncul di sistem pencarian.

Opsional: Menentukan nama index

Secara default, Scout biasanya menggunakan nama tabel sebagai nama index. Jika ingin mengubahnya, tambahkan method berikut:

public function searchableAs(): string
{
    return 'posts_index';
}

Ini berguna jika Anda ingin nama index lebih eksplisit atau berbeda dari nama tabel database.

Menjalankan Import Data Awal

Setelah model siap, data yang sudah ada di database belum otomatis masuk ke Algolia. Anda perlu melakukan import awal:

php artisan scout:import "App\Models\Post"

Perintah ini akan membaca seluruh data model Post lalu mengirimkannya ke index Algolia.

Jika import berhasil, Anda seharusnya bisa melihat index dan records di dashboard Algolia.

Kapan data akan ter-update otomatis?

Setelah model menggunakan trait Searchable, perubahan data baru biasanya akan ikut tersinkronisasi melalui event model Eloquent. Artinya:

  • Create akan menambahkan record ke index.
  • Update akan memperbarui record di index.
  • Delete akan menghapus record dari index.

Namun perilaku ini juga bisa dipengaruhi oleh konfigurasi queue Scout.

Queue atau tanpa queue?

Untuk aplikasi kecil, sinkronisasi langsung mungkin terasa cukup. Tetapi pada aplikasi produksi, indexing sering lebih aman dijalankan melalui queue agar request pengguna tidak tertunda oleh proses komunikasi ke Algolia.

Periksa pengaturan di config/scout.php. Jika queue diaktifkan, maka Anda harus menjalankan worker queue:

php artisan queue:work

Jika worker tidak berjalan, perubahan model mungkin tidak pernah sampai ke Algolia meskipun kode Anda sudah benar.

Contoh Query Pencarian Sederhana

Setelah data terindeks, Anda bisa mulai melakukan pencarian menggunakan method search() dari Scout.

use App\Models\Post;

$posts = Post::search('laravel scout')->get();

Query di atas akan meminta hasil pencarian dari Algolia, lalu mengembalikan model Eloquent yang sesuai. Ini memudahkan integrasi karena Anda tetap bekerja dengan collection model Laravel.

Contoh di controller:

<?php

namespace App\Http\Controllers;

use App\Models\Post;
use Illuminate\Http\Request;

class PostSearchController extends Controller
{
    public function index(Request $request)
    {
        $keyword = $request->get('q', '');

        $posts = empty($keyword)
            ? collect()
            : Post::search($keyword)->get();

        return view('posts.search', compact('posts', 'keyword'));
    }
}

Contoh sederhana pada route:

use App\Http\Controllers\PostSearchController;

Route::get('/search', [PostSearchController::class, 'index']);

Penting untuk diingat bahwa pencarian Scout dengan Algolia bekerja di search index, bukan langsung di database. Jadi jika hasil terasa aneh, sering kali masalahnya ada pada data index, pengaturan ranking, atau field yang dikirim di toSearchableArray().

Troubleshooting Umum

1. APP_ID atau API key salah

Gejala umum:

  • Error autentikasi saat import.
  • Data tidak masuk ke Algolia.
  • Query pencarian gagal.

Yang perlu dicek:

  • Pastikan ALGOLIA_APP_ID benar.
  • Pastikan ALGOLIA_SECRET menggunakan key yang memiliki izin tulis jika dipakai untuk indexing.
  • Jalankan php artisan config:clear setelah mengubah .env.

2. Index belum terisi

Jika pencarian selalu kosong, jangan langsung menyalahkan query. Cek dulu apakah index memang berisi data.

  • Jalankan php artisan scout:import "App\Models\Post".
  • Buka dashboard Algolia dan pastikan records benar-benar ada.
  • Pastikan method toSearchableArray() mengembalikan data yang relevan, bukan array kosong.

3. Queue belum jalan

Jika create/update model tidak muncul di Algolia, kemungkinan queue aktif tetapi worker tidak berjalan.

  • Cek konfigurasi queue di Scout.
  • Jalankan php artisan queue:work.
  • Periksa apakah ada job gagal di sistem queue Anda.

Ini adalah masalah yang sangat umum di environment development maupun server staging.

4. Data berubah di database tetapi hasil pencarian lama masih muncul

Kemungkinan penyebab:

  • Update belum terkirim karena queue macet.
  • Model tidak benar-benar menggunakan trait Searchable.
  • Kolom yang diubah tidak dimasukkan ke toSearchableArray().

Solusi cepat untuk memastikan sinkronisasi ulang adalah menjalankan import ulang model.

5. Hasil pencarian tidak sesuai harapan

Jika hasil ada tetapi kurang relevan, masalahnya belum tentu di Laravel. Bisa jadi Anda perlu menyesuaikan pengaturan index di dashboard Algolia, seperti searchable attributes, ranking, dan custom settings lainnya. Untuk tahap awal, pastikan dulu field seperti title dan content benar-benar dikirim ke index.

Tips Keamanan Dasar

Karena integrasi ini melibatkan API key, keamanan dasar tidak boleh diabaikan:

  • Jangan commit file .env ke repository publik.
  • Jangan gunakan Admin API Key di frontend.
  • Simpan kredensial di environment variable, bukan hardcode di source code.
  • Gunakan Search-Only API Key untuk fitur pencarian di browser.
  • Pertimbangkan key dengan scope terbatas jika kebutuhan akses bisa dipersempit.

Admin API Key yang bocor memungkinkan pihak lain menulis, menghapus, atau memodifikasi index Anda. Dampaknya bukan hanya masalah keamanan, tetapi juga potensi gangguan operasional aplikasi.

Penutup

Integrasi Algolia dengan Laravel Scout adalah cara praktis untuk menambahkan fitur pencarian yang lebih cepat dan lebih nyaman digunakan daripada query database biasa. Alur dasarnya cukup jelas: buat akun Algolia, ambil Application ID dan API key yang tepat, instal Scout dan client Algolia, konfigurasi environment, tambahkan trait Searchable pada model, tentukan data index lewat toSearchableArray(), lalu jalankan import awal.

Untuk pemula, fokuslah dulu pada integrasi dasar yang stabil. Pastikan index terisi, query pencarian bekerja, dan sinkronisasi data berjalan konsisten. Setelah itu, Anda bisa melanjutkan ke fitur yang lebih lanjut seperti filter, faceting, replica index, dan pengaturan ranking di Algolia sesuai kebutuhan aplikasi.

Jika Anda menemui masalah, mulai debugging dari hal paling dasar: kredensial, isi index, cache konfigurasi, dan queue worker. Dalam banyak kasus, masalah integrasi Scout dan Algolia berasal dari salah satu titik tersebut.