Penggunaan Redis sebagai driver cache dan session di Laravel telah menjadi standar de facto untuk aplikasi yang menuntut performa tinggi. Redis mampu menangani operasi baca-tulis dengan kecepatan luar biasa karena sifatnya yang in-memory. Namun, transisi dari driver berbasis file atau database ke Redis sering kali terhenti oleh satu error klasik yang cukup membuat frustrasi, terutama bagi developer yang baru pertama kali mengintegrasikan Redis ke dalam stack aplikasi mereka. Error ini muncul bukan karena logika bisnis yang salah, melainkan karena kesenjangan antara konfigurasi Laravel yang mengasumsikan ketersediaan layanan Redis dengan realita di lingkungan server bahwa ekstensi PHP untuk berkomunikasi dengan Redis belum ada. Dalam artikel ini, kita akan melakukan bedah mendalam mengenai error Class Redis not found, mulai dari anatomi pesannya, akar masalahnya, hingga solusi permanen dan strategi jangka panjang agar error ini tidak kembali muncul di masa depan.

Anatomi pesan error

Ketika error ini terjadi, Laravel akan melempar exception yang menghentikan eksekusi aplikasi secara paksa. Pesan error yang muncul di layar atau di dalam file log biasanya terlihat seperti berikut:

Fatal error: Uncaught Error: Class "Redis" not found in /var/www/html/vendor/laravel/framework/src/Illuminate/Cache/RedisStore.php:45

Atau dalam konteks web, Anda mungkin melihat halaman error Laravel 500 dengan pesan:

Error
Class "Redis" not found

Secara harfiah, pesan Class "Redis" not found memiliki arti yang sangat eksplisit: interpreter PHP yang menjalankan aplikasi Laravel Anda mencoba membuat instance dari sebuah kelas bernama Redis, namun kelas tersebut tidak terdefinisi di ruang lingkup (scope) PHP saat itu. Dalam konteks Laravel, kelas Redis yang dimaksud di sini bukanlah facade Illuminate\Support\Facades\Redis yang biasa Anda panggil di kode Laravel, melainkan kelas bawaan dari ekstensi PHP yaitu phpredis. Laravel secara internal akan menggunakan kelas ini untuk berkomunikasi dengan server Redis jika ekstensi tersebut tersedia.

Error ini muncul karena alur kerja berikut: di dalam file konfigurasi config/database.php atau config/cache.php, Anda telah menetapkan driver Redis sebagai koneksi default. Ketika aplikasi booting atau ketika ada kode yang memanggil Cache::get() atau Redis::set(), Laravel akan meresolve dependensi ini melalui Service Container. Container ini kemudian akan memanggil Redis Manager yang bertugas menginstansiasi koneksi. Secara default, Laravel akan mendeteksi apakah ekstensi C (phpredis) ada di sistem. Jika ada, ia akan menggunakan kelas Redis atau RedisCluster. Jika tidak, ia akan fallback ke paket predis/predis. Namun, dalam banyak kasus, composer dependency untuk predis sengaja dihapus karena developer ingin menggunakan ekstensi C yang lebih cepat, sementara ekstensi C-nya sendiri belum terinstalasi di server. Hasilnya? PHP gagal menemukan kelas Redis, dan Fatal Error pun terlempar sebelum Laravel sempat melakukan fallback atau menangani kondisi tersebut.

Kenapa ini terjadi

Kegagalan menemukan kelas Redis bukanlah masalah tunggal, melainkan bisa disebabkan oleh beberapa faktor yang saling tumpang tindih. Memahami akar masalah ini adalah kunci utama sebelum kita melangkah ke solusi, karena menerapkan solusi yang salah untuk root cause yang berbeda hanya akan membuang waktu.

  1. Ekstensi phpredis belum terinstalasi di sistem (Penyebab Paling Sering): Ini adalah akar masalah yang paling klasik. Ekstensi phpredis adalah modul C yang dikompilasi khusus untuk PHP. Berbeda dengan paket Composer yang hanya berisi kode PHP murni, ekstensi C harus dikompilasi atau diinstalasi melalui manajer paket sistem operasi dan diaktifkan di dalam file php.ini. Banyak developer yang mengasumsikan bahwa mendeklarasikan konfigurasi Redis di Laravel sudah cukup, tanpa menyadari bahwa PHPbutuh "jembatan" berupa ekstensi ini untuk bisa berbicara dengan server Redis.

  2. Ekstensi terinstalasi, tapi tidak diaktifkan di php.ini: Kasus ini sering terjadi di lingkungan Linux. Anda mungkin telah berhasil menginstal paket php-redis melalui apt atau yum, namun lupa untuk mengaktifkannya menggunakan perintah phpenmod, atau Anda belum me-restart service web server (Nginx/Apache) dan PHP-FPM setelah instalasi. Modul mungkin sudah ada di folder /etc/php/mods-available/, namun belum ada symlink-nya di /etc/php/8.x/fpm/conf.d/.

  3. Menghapus paket predis/predis dari Composer: Laravel secara default menyertakan predis/predis sebagai fallback driver Redis yang berbasis PHP murni. Jika Anda menjalankan composer remove predis/predis untuk mengurangi ukuran vendor atau karena ingin sepenuhnya beralih ke ekstensi C, namun ekstensi C (phpredis) belum siap di server, maka aplikasi akan langsung crash. Tanpa predis dan tanpa phpredis, Laravel sama sekali tidak memiliki driver untuk berkomunikasi dengan Redis.

  4. Ketidakcocokan versi PHP saat upgrade: Ketika Anda melakukan upgrade versi PHP (misalnya dari PHP 8.0 ke 8.2), ekstensi phpredis untuk versi lama tidak akan kompatibel dengan versi baru. Anda harus menginstalasi ulang ekstensi yang sesuai dengan versi PHP yang baru (contoh: dari php8.0-redis ke php8.2-redis).

  5. Discrepancy antara PHP CLI dan PHP Web (CGI/FPM): Ini adalah jebakan yang sangat licin. Anda mungkin menjalankan php -m | grep redis di terminal dan melihat bahwa ekstensi Redis terdaftar, namun aplikasi web tetap error. Ini terjadi karena environment PHP CLI (php-cli.ini) dan environment web server (php-fpm.ini atau php-apache2.ini) sering kali menggunakan file konfigurasi yang berbeda dan memuat modul yang berbeda pula.

Untuk memastikan penyebab mana yang sedang Anda alami, langkah diagnostik pertama adalah mengecek ketersediaan modul melalui terminal. Jalankan perintah php -m | grep redis. Jika tidak menghasilkan output apa pun, maka Anda berada di kasus nomor 1 (ekstensi belum ada). Jika muncul kata redis, namun web tetap error, Anda berada di kasus nomor 2 (belum restart) atau kasus nomor 5 (discrepancy CLI vs Web). Buatlah file phpinfo.php dengan konten <?php phpinfo(); ?> di document root Anda, akses melalui browser, dan cari kata "Redis". Jika tidak ditemukan di sana, berarti PHP-FPM/Apache tidak memuat ekstensi tersebut.

Memperbaiki error ini

Memperbaiki error ini membutuhkan pendekatan yang presisi sesuai dengan sistem operasi dan environment yang Anda gunakan. Kita akan membahas solusi langkah demi langkah, dengan fokus utama pada instalasi ekstensi phpredis karena merupakan penyebab paling umum dan menawarkan performa terbaik.

Langkah 1: Instalasi Ekstensi phpredis di Ubuntu/Debian

Untuk pengguna Ubuntu atau Debian, instalasi ekstensi ini sangat mudah berkatikan adanya paket bawaan di repositori Ondrej PPA. Asumsikan Anda menggunakan PHP 8.2. Jalankan perintah berikut di terminal server Anda:

# Update daftar paket
sudo apt-get update

# Instal ekstensi phpredis untuk PHP 8.2
sudo apt-get install php8.2-redis -y

# Aktifkan modul dan restart PHP-FPM serta Nginx/Apache
sudo phpenmod redis
sudo systemctl restart php8.2-fpm
sudo systemctl restart nginx

Contoh output setelah menjalankan perintah instalasi adalah pesan bahwa paket berhasil diunduh dan dikonfigurasi. Setelah restart, ekstensi harusnya sudah aktif. Anda bisa memverifikasinya dengan menjalankan:

php -m | grep redis
# Keluaran yang tampak: redis

Langkah 2: Instalasi di CentOS/RHEL/Fedora

Di keluarga Red Hat, paket ekstensi PHP tidak selalu tersedia secara default di repositori base. Anda perlu mengaktifkan repositori EPEL (Extra Packages for Enterprise Linux) dan Remi.

# Tambahkan repositori EPEL dan Remi
sudo dnf install epel-release -y
sudo dnf install https://rpms.remirepo.net/enterprise/remi-release-9.rpm -y

# Aktifkan modul PHP yang diinginkan (misalnya 8.2)
sudo dnf module reset php -y
sudo dnf module enable php:remi-8.2 -y

# Instal ekstensi Redis
sudo dnf install php-pecl-redis5 -y

# Restart web server dan PHP-FPM
sudo systemctl restart php-fpm
sudo systemctl restart httpd

Langkah 3: Solusi Alternatif Menggunakan Predis (Tanpa Akses Root)

Jika Anda tidak memiliki akses sudo ke server (misalnya di shared hosting tradisional), Anda tidak bisa menginstal ekstensi C. Solusi permanen dan langsung untuk root cause ini adalah mengembalikan paket predis melalui Composer. Predis adalah library PHP murni yang sangat stabil, meskipun tidak secepat ekstensi C.

composer require predis/predis

Setelah ini, Laravel akan secara otomatis menggunakan Predis ketika kelas Redis (dari ekstensi C) tidak ditemukan, dan error pun akan hilang. Solusi ini bersifat permanen selama paket predis tetap ada di file composer.json Anda.

Langkah 4: Konfigurasi Khusus untuk Pengguna Docker

Jika Anda menggunakan image Docker resmi seperti php:8.2-fpm, ekstensi Redis tidak ikut terbawa secara default. Anda harus mengkompilasinya secara manual di dalam Dockerfile.

FROM php:8.2-fpm

# Instal dependensi sistem untuk pecl
RUN apt-get update && apt-get install -y \
    libzip-dev \
    && pecl install redis \
    && docker-php-ext-enable redis

Build ulang image Anda dengan docker-compose build app (sesuaikan nama service), dan container Anda akan memiliki ekstensi Redis yang siap pakai.

Verifikasi Solusi Berhasil

Cara paling mutlak untuk memverifikasi bahwa solusi di atas berhasil adalah dengan menjalankan Tinker di dalam proyek Laravel Anda. Tinker berjalan di environment yang sama dengan web server Anda (jika menggunakan PHP CLI yang sama).

php artisan tinker
# Di dalam shell tinker, jalankan:
>>> Redis::connection()->ping();
# Yang akan kamu lihat: "PONG" atau true

>>> Cache::store('redis')->put('test_key', 'hello_redis', 60);
=> true

>>> Cache::store('redis')->get('test_key');
=> "hello_redis"

Jika Anda mendapatkan respons PONG dan berhasil menyimpan serta membaca cache, maka error Class "Redis" not found telah sepenuhnya terselesaikan.

Solusi jangka panjang

Memperbaiki error saat aplikasi sedang down adalah satu hal, namun memastikan error tersebut tidak kembali muncul ketika Anda melakukan deployment ke server baru atau melakukan scaling adalah hal yang jauh lebih penting. Solusi jangka panjang membutuhkan pendekatan infrastruktur sebagai kode (Infrastructure as Code) dan disiplin dalam konfigurasi.

Konfigurasi pencegahan

Di dalam Laravel, ada sebuah gotcha konfigurasi yang sering diabaikan. Buka file config/database.php. Di dalam koneksi redis, terdapat opsi client. Secara default, nilainya adalah phpredis. Jika Anda tahu bahwa infrastruktur Anda tidak mendukung ekstensi C (misalnya karena keterbatasan server), Anda harus secara eksplisit mengaturnya ke predis untuk mencegah Laravel mencari kelas Redis yang tidak ada.

// config/database.php
'redis' => [
    'client' => env('REDIS_CLIENT', 'phpredis'),
    // ... konfigurasi lainnya
],

Kebiasaan yang baik yang sangat direkomendasikan adalah mengambil nilai ini dari file .env. Dengan cara ini, Anda bisa menggunakan phpredis di server production yang Anda kendalikan penuh, dan menggunakan predis di lingkungan local atau CI/CD yang mungkin tidak memiliki ekstensi C.

# .env di Production Server
REDIS_CLIENT=phpredis

# .env di Local/CI Server
REDIS_CLIENT=predis

Kebiasaan yang baik Manajemen Ekstensi

  1. Dokumentasikan Server Provisioning: Jangan pernah menginstal ekstensi secara manual lalu melupakannya. Gunakan tools seperti Ansible, Chef, atau Puppet, atau deklarasikan di dalam Dockerfile. Buat playbook Ansible yang memastikan paket php8.x-redis selalu terinstalasi setiap kali ada server baru yang di-spin up.

  2. Health Check Script: Buatlah skrip sederhana yang dijalankan oleh sistem monitoring atau load balancer Anda untuk mengecek kesehatan koneksi Redis dan ekstensinya.

// routes/web.php atau di dalam sebuah Artisan Command
Route::get('/health', function () {
    try {
        $redisExt = extension_loaded('redis');
        $ping = Redis::connection()->ping();
        return response()->json([
            'status' => 'ok',
            'phpredis_ext' => $redisExt,
            'redis_ping' => $ping
        ]);
    } catch (\Exception $e) {
        return response()->json(['status' => 'error', 'message' => $e->getMessage()], 500);
    }
});

Perbedaan OS dan Environment

Sangat krusial untuk memahami bahwa manajemen ekstensi PHP sangat bergantung pada Sistem Operasi. Di Ubuntu/Debian, ekstensi dikontrol melalui phpenmod dan phpdismod yang mengelola symlink di dalam direktori konfigurasi PHP. Di CentOS/RHEL, file .ini harus diedit secara manual untuk menambahkan extension=redis.so, atau dikelola melalui dnf. Di macOS (untuk local development), pengguna Homebrew harus menggunakan pecl install redis dan kemudian menambahkan extension="redis.so" ke dalam /opt/homebrew/etc/php/8.x/php.ini. Di Windows (XAMPP/Laragon), Anda harus mengunduh file .dll yang sudah dikompilasi (pecl.php.net) dan memasukkannya ke folder ext, lalu mendaftarkannya di php.ini. Ketidaktahuan akan perbedaan alur kerja ini di tiap OS sering kali membuat developer terjebak dalam error berjam-jam, padahal mekanisme dasarnya sama: PHP perlu tahu di mana library shared object (.so atau .dll) itu berada.

Troubleshooting lanjutan

Jika Anda telah mengikuti semua langkah di atas—menginstal ekstensi, me-restart server, dan memverifikasi melalui CLI—namun aplikasi web Anda masih melempar error Class "Redis" not found, maka Anda memasuki wilayah edge case yang membutuhkan troubleshooting lebih mendalam.

Kasus Khusus: Discrepancy CLI vs PHP-FPM

Seperti yang disinggung sebelumnya, ini adalah biang kerok paling umum dari solusi yang "work di terminal tapi gagal di browser". Ketika Anda menjalankan php -m, Anda menggunakan konfigurasi PHP CLI. Namun, ketika Nginx atau Apache memproses request web, ia meneruskannya ke PHP-FPM (atau mod_php), yang memiliki file konfigurasi terpisah. Untuk memastikan PHP-FPM memuat ekstensi Redis, jangan mengandalkan CLI. Periksa langsung file konfigurasi FPM.

Jalankan perintah untuk menemukan file php.ini yang digunakan oleh FPM:

php -i | grep "Additional .ini files parsed"
# Atau secara spesifik untuk FPM, cari di:
ls /etc/php/8.x/fpm/conf.d/

Pastikan ada file seperti 20-redis.ini di dalam direktori tersebut. Jika tidak ada, buat symlink secara manual dari mods-available ke conf.d, atau jalankan sudo phpenmod redis yang seharusnya melakukannya untuk Anda. Setelah itu, wajib jalankan sudo systemctl restart php8.x-fpm. Tanpa restart, proses FPM yang sudah berjalan tidak akan memuat konfigurasi baru.

Cara Baca Log untuk Deep-Dive

Jika aplikasi masih error, jangan hanya mengandalkan layar error browser yang sering kali ditutupi oleh debugbar atau pesan generik 500. Baca log mentah (raw logs) secara langsung.

  1. Log Laravel: Buka storage/logs/laravel.log. Gulir ke bagian paling bawah dan cari stack trace error Class "Redis" not found. Perhatikan file dan baris yang memicu pemanggilan. Apakah itu dari CacheManager atau dari kode kustom Anda yang langsung memanggil new \Redis()? Jika kode Anda langsung menginstansiasi new \Redis(), Anda harus mengubahnya menjadi Redis::connection()->client() agar mengikuti factory pattern Laravel yang bisa di-fallback ke Predis.

  2. Log PHP-FPM: Cek log error FPM di /var/log/php8.x-fpm/error.log (Ubuntu) atau /var/log/php-fpm/error.log (CentOS). Kadang-kadang, ekstensi gagal dimuat karena segmentation fault atau konflik versi, dan error ini hanya terlihat di log level sistem, bukan di log aplikasi Laravel.

  3. Log Web Server: Cek /var/log/nginx/error.log. Terkadang Nginx melempar error 502 Bad Gateway karena PHP-FPM crash akibat ekstensi yang rusak saat booting, sebelum Laravel sempat menangkap exception-nya.

Referensi lanjutan

Jika semua upaya di atas masih gagal, atau Anda ingin memahami internal ekstensi ini secara mendalam untuk keperluan debugging tingkat lanjut, berikut adalah sumber resmi yang harus Anda rujuk:

  1. Repositori Resmi phpredis: Kunjungi github.com/phpredis/phpredis. Di bagian Issues repositori ini, Anda bisa menemukan diskusi mendalam mengenai bug kompilasi untuk versi PHP tertentu, masalah dengan ARM architecture (seperti Apple Silicon M1/M2), atau konflik dengan ekstensi lain seperti Xdebug yang terkadang menyebabkan segfault saat pertama kali dijalankan.

  2. Dokumentasi Laravel: Baca bagian Laravel Cache dan Laravel Redis. Pahami bagaimana Laravel melakukan resolusi driver dan bagaimana konfigurasi REDIS_CLIENT mengubah perilaku Service Container secara drastis.

  3. Dokumentasi PHP: Pahami mekanisme php.ini dan Dynamic Extensions di php.net. Ini akan memberi Anda wawasan mengapa phpenmod bekerja di Debian dan mengapa Anda harus me-restart service setelah mengubah konfigurasi, karena PHP memuat ekstensi pada saat proses startup, bukan secara on-the-fly.

Dengan pemahaman yang komprehensif mulai dari anatomi error, perbedaan environment, hingga cara membaca log sistem, Anda tidak hanya memperbaiki error Class "Redis" not found, tetapi juga memperkuat arsitektur deployment aplikasi Laravel Anda untuk menjadi lebih robust dan tahan terhadap perubahan infrastruktur di masa depan.