Masalah Umum

Perintah php spark shield:* tidak ditemukan

Padahal paket sudah terpasang. Perintah shield:* ditemukan otomatis dari namespace PSR-4 package; provider bukan yang mendaftarkannya. Biasanya penyebabnya autoload Composer yang belum diperbarui atau perintah dijalankan dari folder yang salah.

Perbaikan: jalankan composer dump-autoload, lalu cek dari root aplikasi:

php spark list | findstr shield

Kalau masih kosong, pastikan vendor/ganadev/codeigniter4-shield benar-benar ada. Provider bukan syarat untuk command; provider diperlukan untuk mendaftarkan service, alias filter, dan filter default. Kalau aplikasi punya app/Config/Commands.php, provider juga mendaftarkan command ke sana.

Filter firewall tidak terpasang

Shield tidak memblokir apa pun padahal mode sudah enforce. Kemungkinan terbesar: service provider belum dipanggil, sehingga filter default tidak didaftarkan.

Perbaikan: tambahkan di app/Config/Events.php:

Events::on('pre_system', static function (): void {
    \Ganadev\Shield\Codeigniter\ShieldServiceProvider::register();
});

Kalau provider sudah dipanggil tetapi /.env tetap tidak terdeteksi, itu bukan bug: filter default (globals['before']) berjalan setelah router, jadi path tanpa route tidak pernah sampai ke filter. Instalasi default memasang required['before'] + ShieldGateFilter untuk menutupinya — lihat Registrasi & Urutan Filter.

Cek dengan route yang benar-benar ada (lihat php spark routes) dan kirim payload yang memicu rule. /.env bukan route, jadi tidak bisa dipakai sebagai uji filter default; request itu berhenti di PageNotFoundException sebelum filter berjalan. Kalau Anda memakai setup required['before'], /.env justru bisa dipakai sebagai uji.

ConfigException saat mengatur proxyIPs

Gejala: ConfigException dengan pesan You must set an array with Proxy IP address key and HTTP header name value in Config\App::$proxyIPs.

Penyebab: format array salah. CodeIgniter 4.3+ mengharuskan format asosiatif (IP/CIDR → nama header), bukan array numerik.

Perbaikan:

public array $proxyIPs = [
    '173.245.48.0/20' => 'CF-Connecting-IP',
    '103.21.244.0/22' => 'CF-Connecting-IP',
    // ...
];

Semua pengunjung terlihat dari satu IP

Gejala: challenge muncul untuk semua orang, atau ban menjangkiti semua pengguna sekaligus.

Penyebab: aplikasi di belakang proxy (Cloudflare, load balancer) tapi proxyIPs di app/Config/App.php tidak diisi, sehingga IP proxy terbaca sebagai IP klien.

Perbaikan: isi proxyIPs dengan rentang CIDR proxy Anda (lihat Instalasi). Lakukan sebelum menaikkan mode.

Mode observe tapi tidak memblokir

Itu memang perilakunya. observe = mencatat, tidak menjalankan keputusan. Naikkan ke challenge lebih dulu, lalu enforce setelah yakin tidak ada false positive:

shield.mode = challenge

Gunakan shield.mode = enforce setelah masa observasi selesai. SHIELD_MODE tidak dibaca karena nama properti config adalah mode.

Mengubah .env tidak berefek di php spark serve

Server built-in CI4 adalah satu proses panjang; DotEnv memanggil putenv() yang bertahan selama proses hidup. Perubahan .env tidak efek sampai proses di-restart.

Perbaikan: restart server (Ctrl+C lalu php spark serve lagi) setiap mengubah nilai config shield.*. Di Apache/Nginx dengan model per-request, restart tidak diperlukan.

Widget reCAPTCHA tidak muncul di localhost

1. Driver memakai reCAPTCHA v2 checkbox. Pastikan challengeDriver bernilai recaptcha dan SHIELD_RECAPTCHA_SITE_KEY sudah diisi.
2. Daftarkan localhost pada daftar domain key reCAPTCHA, lalu akses lewat http://localhost:8080, bukan 127.0.0.1.
3. Jika widget tetap kosong, periksa console browser: script https://www.google.com/recaptcha/api.js harus termuat.

Halaman admin tidak bisa dikunjungi (404 / tidak ada route)

Route admin hanya didaftarkan kalau adminEnabled bernilai true. Defaultnya false. Periksa app/Config/Shield.php:

public bool $adminEnabled = true;
public string $adminAuthorize = 'admin.authorize';

Jangan biarkan adminAuthorize kosong. Nilai kosong berarti siapa saja boleh membuka panel admin; isi dengan filter otorisasi yang benar. Endpoint GET /shield/health akan memberi peringatan bila nilainya kosong.

Permintaan ke URL tanpa route tidak terpantau

Request seperti /.env tidak menyentuh filter globals['before'] karena CodeIgniter melempar PageNotFoundException sebelum filter berjalan. Ini perilaku default, bukan berarti Shield tidak bisa menanganinya.

Perbaikan: pasang ShieldGateFilter di required['before'] dan hapus shield.firewall dari global filter — lihat Registrasi & Urutan Filter. Instalasi default sudah memakai pola ini. Dengan begitu, request 404/scanner diperiksa sebelum router dan 404-nya tetap dihitung.

Kalau memilih registrasi default, andalkan WAF di depan server atau aturan mod_rewrite untuk URL tersebut.

Semua orang kena challenge berulang

1. Trusted cookie tidak tersimpan. Pastikan HTTPS (atau localhost di development); request HTTP tidak mengirim cookie Secure kembali. trustedTtlMinutes mengatur masa berlakunya.
2. trustedEnabled mati. Kalau false, tidak ada cookie sama sekali.
3. thresholdChallenge terlalu kecil untuk traffic Anda. Cek shield:report.

Pengunjung asli masih diblokir

Ini hampir selalu masalah IP: semua pengguna “sama” karena proxyIPs kosong. Baca baris “Semua pengunjung terlihat dari satu IP” di atas. Kalau bukan itu, cari IP yang diblokir curiga di shield:report, lalu shield:release.

Blokir mengembalikan HTML, padahal kliennya API

Shield mendeteksi API lewat apiPaths dan apiDetectAccept. Pastikan path API Anda masuk apiPaths:

public array $apiPaths = ['/api'];

Atau pastikan klien mengirim Accept: application/json / X-Requested-With: XMLHttpRequest agar apiDetectAccept mengenalinya.

Ban tidak hilang setelah shield:release

shield:release memakai CachedBanRepository, jadi cache ikut dibersihkan. Kalau IP masih terblokir:

1. Pastikan IP yang dilepas benar — di belakang proxy, IP bisa berbeda.
2. Cek apakah masih ada ban aktif lain, atau event baru yang membuat ban lagi.
3. Perubahan langsung di database/SQL tidak membersihkan cache. Tunggu banCacheTtlSeconds (default 30 detik) atau bersihkan cache aplikasi.
4. Release tidak mereset offense; bila IP menyerang lagi, ia bisa langsung ban lagi atau lebih lama.

shield:prune tidak berjalan otomatis

CodeIgniter tidak punya scheduler. Tambahkan cron:

* * * * * cd /path/ke/aplikasi && php spark shield:prune >> /dev/null 2>&1

Tanpa itu, security_events tumbuh tanpa batas.

Googlebot tidak bisa mengindeks situs

1. Pastikan crawlerVerificationEnabled true.
2. Jalankan shield:health — hostname terverifikasi atau tidak.
3. Pastikan server Anda bisa melakukan reverse DNS keluar (beberapa host memblokir port 53 dari aplikasi).

Apa selanjutnya kalau tidak ada yang cocok di sini

Buka Pertanyaan Umum, atau lihat Shield :health untuk gejala teknis. Kalau tetap mentok, laporkan lewat Issues repository.