PHP EnvCrypt Template

Template reusable untuk project PHP yang perlu membaca .env berisi value terenkripsi dengan format kompatibel envcrypt.

Format yang didukung:

encrypted:<base64(nonce + ciphertext + tag)>

Detail kompatibilitas:

• Algorithm: AES-256-GCM
• Key: 32 byte / 64 hex chars
• Nonce/IV: 12 byte
• Auth tag: 16 byte
• Payload: nonce(12) + ciphertext + tag(16)

Kapan template ini dipakai?

Gunakan template ini ketika:

• Project PHP native di shared hosting/CyberPanel perlu menyimpan secret secara aman.
• .env perlu tetap bisa dibaca aplikasi, tapi value rahasianya tidak plaintext.
• Agentic coding/AI sering membaca folder project dan kamu ingin mengurangi risiko secret terbaca.
• Kamu ingin standar bootstrap yang sama untuk banyak project PHP.

Template ini melindungi secret saat tersimpan di file. Saat runtime, value tetap menjadi plaintext di getenv(), $_ENV, dan $_SERVER agar aplikasi PHP bisa memakainya.

Struktur template

php-envcrypt-template/
├── src/EnvCrypt.php
├── bin/envcrypt-php
├── scripts/install-envcrypt.php
├── scripts/lint.php
├── tests/compat.php
├── tests/install.php
├── examples/
│   ├── native/
│   │   ├── .env.example
│   │   └── public_html/index.php
│   └── frameworks/
│       ├── laravel-bootstrap.php
│       └── codeigniter4-preload.php
└── composer.json

Flow terbaik untuk PHP native/shared hosting

Struktur yang disarankan:

project/
├── src/
│   └── EnvCrypt.php
├── .env
└── public_html/
    └── index.php

Jangan taruh .env di dalam public_html. Template ini juga mengabaikan .env dan .env.* dari Git secara default agar secret tidak ikut ter-commit. Jika terpaksa menaruh .env di area web, blokir akses web server dengan .htaccess.

Bootstrap di public_html/index.php:

<?php

require_once __DIR__ . '/../src/EnvCrypt.php';

use Jankricuntuk\EnvCrypt\EnvCrypt;

EnvCrypt::load(__DIR__ . '/../.env');

Jika entrypoint project ada di root index.php, path-nya berbeda:

require_once __DIR__ . '/src/EnvCrypt.php';

\Jankricuntuk\EnvCrypt\EnvCrypt::load(__DIR__ . '/.env');

Contoh .env:

APP_ENV=production
DB_HOST=localhost
DB_PASSWORD=encrypted:replace-with-envcrypt-value
API_KEY=encrypted:replace-with-envcrypt-value

Setelah load, value bisa dipakai seperti biasa:

$password = getenv('DB_PASSWORD');

Flow untuk framework

Laravel

Laravel sudah punya loader .env, jadi jangan asal mengganti workflow-nya. Pilihan aman:

1. Load EnvCrypt::load() sebelum Laravel membaca config.
2. Jangan commit key ke repository.
3. Pastikan config cache dibuat setelah env terenkripsi bisa didekripsi di server.

Contoh preload ada di:

examples/frameworks/laravel-bootstrap.php

Konsepnya:

require_once __DIR__ . '/../vendor/autoload.php';

\Jankricuntuk\EnvCrypt\EnvCrypt::load(__DIR__ . '/../.env');

Untuk Laravel production, jalankan ini sebelum config:cache, atau buat service/bootstrap khusus yang berjalan sebelum konfigurasi final dipakai.

CodeIgniter 4 / framework custom

Tambahkan loader sebelum framework bootstrap di public/index.php:

require_once __DIR__ . '/../vendor/autoload.php';

\Jankricuntuk\EnvCrypt\EnvCrypt::load(__DIR__ . '/../.env');

Contoh ada di:

examples/frameworks/codeigniter4-preload.php

Symfony atau framework lain

Gunakan prinsip yang sama:

1. Load file .env terenkripsi seawal mungkin.
2. Pastikan berjalan sebelum container/config membaca env.
3. Untuk production, pertimbangkan env var server langsung untuk secret paling sensitif.

Cara menyimpan key

Prioritas rekomendasi:

1. Environment variable server

Paling cocok untuk shared hosting yang mendukung pengaturan env:

ENVCRYPT_KEY=64hexcharacters...

2. Config di luar webroot

Jika server tidak mudah mengatur env var, simpan di luar public_html:

/home/user/.envcrypt.yaml

Isi file:

key: "64hexcharacters..."

Jangan commit .envcrypt.yaml ke repository. Untuk shared hosting, set permission file key seketat mungkin:

chmod 600 ~/.envcrypt.yaml

Command kecil bawaan

Generate key:

php bin/envcrypt-php key:generate

Decrypt satu value:

ENVCRYPT_KEY='64hexkey...' php bin/envcrypt-php decrypt:value 'encrypted:...'

Cek load .env:

ENVCRYPT_KEY='64hexkey...' php bin/envcrypt-php load:check .env

Hindari menulis key langsung sebagai argumen command jika server dipakai banyak user, karena argumen bisa tersimpan di shell history atau terlihat di process list.

Batas parser .env

Parser template ini sengaja sederhana agar cocok untuk shared hosting tanpa dependency tambahan. Yang didukung:

• Baris KEY=VALUE
• Komentar yang diawali #
• Quote luar sederhana: "value" atau 'value'
• Value terenkripsi dengan prefix encrypted:

Yang tidak ditargetkan: ekspansi variabel kompleks, multiline dotenv, dan escape rule khusus framework. Untuk kebutuhan itu, load envcrypt sebelum dotenv framework atau adaptasikan loader sesuai parser framework.

Agentic auto-detection flow

Saat agent/AI membuat atau membuka project PHP, gunakan rule ini:

1. Deteksi PHP project dari composer.json, index.php, public/index.php, public_html/index.php, artisan, atau file *.php.
2. Jika project memakai secret .env, pasang src/EnvCrypt.php atau package ini.
3. Deteksi entrypoint:
   • Native/shared hosting: public_html/index.php, public/index.php, atau index.php.
   • Laravel: bootstrap/app.php atau bootstrap sebelum config dibaca.
   • CodeIgniter/custom: public/index.php.
4. Inject EnvCrypt::load() sebelum aplikasi membaca config/database.
5. Pastikan key tidak masuk repo: gunakan ENVCRYPT_KEY atau .envcrypt.yaml di luar webroot.
6. Tambahkan test decrypt kecil sebelum deploy.
7. Dokumentasikan di README project tempat key disimpan dan cara rotasi key.

Rekomendasi lain

Untuk project besar, lebih baik ubah template ini menjadi Composer package private/public agar semua project cukup menjalankan:

composer require jankricuntuk/php-envcrypt-template

Untuk secret yang sangat sensitif, pertimbangkan juga secret manager dari provider hosting/VPS. envcrypt cocok untuk mengurangi risiko secret bocor dari file project, tetapi bukan pengganti penuh untuk secret manager production.

Verifikasi

Lint semua file PHP:

composer run lint

Test kompatibilitas decrypt:

composer run test

Atau tanpa Composer:

php scripts/lint.php
php tests/compat.php
php tests/install.php