Environment & .env

Shield memakai config class yang mewarisi CodeIgniter\Config\BaseConfig. Artinya CodeIgniter 4 sudah memetakan variabel .env ke properti config secara otomatis. Anda tidak perlu memanggil env() di deklarasi properti.

Cara kerja singkat

Saat config('Shield') dipanggil:

1. Paket memakai app/Config/Shield.php jika ada.
2. Jika tidak ada, paket memakai config bawaannya.
3. BaseConfig mencari variabel .env yang cocok dan mengganti properti bertipe scalar.
4. Nilai dari .env menang atas nilai di config class.

Karena class bernama Shield, prefix pendeknya adalah shield (huruf kecil). Anda bisa memakai titik atau garis bawah:

shield.mode = observe
shield.appId = toko-online
shield.thresholdChallenge = 10

Atau bentuk underscore:

shield_mode = observe
shield_appId = toko-online
shield_thresholdChallenge = 10

Jangan pakai env() sebagai nilai default properti

Kode seperti ini bukan PHP yang valid karena default properti harus berupa constant expression, bukan pemanggilan fungsi:

public string $mode = env('SHIELD_MODE', 'observe');

Cukup tulis nilai default biasa. BaseConfig yang akan menggantinya dari .env.

Aturan penamaan

• Prefix dan nama properti case-sensitive di Linux.
• Gunakan nama properti persis seperti di class: thresholdChallenge, bukan threshold_challenge atau THRESHOLD_CHALLENGE.
• SHIELD_MODE, SHIELD_APP_ID, dan uppercase SHIELD_* lain tidak dibaca otomatis untuk properti config. Ganti menjadi shield_mode, shield_appId, dan seterusnya.
• .env hanya mengganti properti scalar yang sudah ada. Anda tidak bisa menambah properti baru atau mengubah scalar menjadi array lewat .env. Untuk array seperti sensitivePaths atau allowlistIps, tulis di config class.

Pengecualian: kunci challenge dibaca langsung oleh paket dengan getenv() dan tetap memakai nama uppercase:

SHIELD_TURNSTILE_SITE_KEY=0x4AAAAAAA...
SHIELD_TURNSTILE_SECRET_KEY=0x4AAAAAAA...
SHIELD_RECAPTCHA_SITE_KEY=...
SHIELD_RECAPTCHA_SECRET_KEY=...

SHIELD_TURNSTILE_VERIFY_URL dan SHIELD_RECAPTCHA_VERIFY_URL juga dibaca langsung jika Anda perlu mengganti endpoint verifikasi.

Config class (opsional)

Buat app/Config/Shield.php hanya jika Anda ingin mengubah nilai default. Warisi config paket, lalu tulis properti yang ingin diubah:

<?php

namespace Config;

class Shield extends \Ganadev\Shield\Codeigniter\Config\Shield
{
    public string $appId = 'toko-online';
    public string $challengeDriver = 'turnstile';

    public array $sensitivePaths = [
        '/login',
        '/admin/login',
        '/api/auth',
    ];
}

Tidak perlu menulis ulang semua properti. Nilai yang tidak diubah tetap memakai default paket. Jangan extends CodeIgniter\Config\BaseConfig langsung; Anda akan kehilangan default Shield.

Jika config class tidak dibuat

Shield tetap berjalan dengan config bawaan paket. Variabel .env dengan prefix shield_ tetap dapat mengganti properti scalar karena class bawaan juga mewarisi BaseConfig.

Contoh .env minimal

shield_mode = observe
shield_appId = toko-online
shield_thresholdChallenge = 10

SHIELD_TURNSTILE_SITE_KEY=0x4AAAAAAA...
SHIELD_TURNSTILE_SECRET_KEY=0x4AAAAAAA...

Untuk development tanpa challenge, gunakan driver null:

shield_challengeDriver = null

Nilai null, test, 0, atau string kosong memakai NullTestDriver. Nilai driver yang tidak dikenal tidak melempar error; Shield jatuh ke Turnstile.

Config cache

Jika configCacheEnabled aktif di app/Config/Optimize.php, perubahan .env tidak langsung terlihat. Nonaktifkan selama development:

public bool $configCacheEnabled = false;
public bool $locatorCacheEnabled = false;

Di produksi, cache boleh aktif, tetapi hapus cache setiap kali .env atau config class berubah.

Batas yang perlu diketahui

• Filter firewall hanya menerima path, bukan query string.
• Path yang tidak cocok dengan route tidak melewati filter globals['before']. Untuk memeriksanya sebelum router, gunakan setup required['before'] + ShieldGateFilter di Registrasi & Urutan Filter.
• Cookie challenge selalu memakai secure: true; challenge lewat HTTP murni dapat memicu SecurityException.
• shield_mode hanya menerima observe, challenge, atau enforce. Nilai lain tidak diabaikan diam-diam: saat engine dibangun, ShieldConfig melempar InvalidConfigException. Pastikan ejaannya benar.

Checklist produksi

• shield_mode = enforce setelah masa observasi.
• shield_appId unik untuk tiap aplikasi.
• Config\App::$proxyIPs berisi CIDR proxy yang benar (array asosiatif, bukan '*').
• Kunci Turnstile/reCAPTCHA terisi. Gunakan driver null hanya di development/test.
• shield_challengeDriver dieja benar; typo akan jatuh ke Turnstile.
• Config cache dihapus setelah perubahan .env.
• php spark shield:health berhasil.
• php spark shield:prune terjadwal.
• Jika admin diaktifkan, adminAuthorize tidak kosong.
• Aplikasi berjalan di HTTPS.