Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk

Blog / Konfigurasi / Panduan Konfigurasi Environmen...
Konfigurasi

Panduan Konfigurasi Environment Laravel: .env, Database, Cache, dan Application Key

AD

Admin HijrahKreativa

Penulis

19 Oct 2026
8 min read
22 views

Overview

Masalah yang diselesaikan. Konfigurasi adalah sumber bug yang paling menjengkelkan: "di laptop jalan, di server error", perubahan .env yang tidak berefek, env() yang tiba-tiba mengembalikan null setelah deploy, atau rahasia yang ikut ter-commit ke GitHub.

Hasil akhir: Anda memahami cara kerja .env dan folder config/, tahu fungsi APP_KEY, bisa mengonfigurasi database, cache, session, dan queue, serta punya pola aman untuk pengelolaan konfigurasi di tiap lingkungan (lokal, staging, production).

Prerequisites

Komponen

Kebutuhan

PHP

8.3+ (Laravel 13) atau 8.2+ (Laravel 12)

Laravel

12.x atau 13.x

Database

MySQL 8.x / MariaDB / SQLite

Opsional

Redis (untuk cache, session, dan queue)

Terminal

PowerShell atau terminal Laragon

Step-by-Step Tutorial

1. Cara Kerja Konfigurasi di Laravel

.env  ──(dibaca oleh env())──►  config/*.php  ──(dibaca oleh config())──►  kode aplikasi

Elemen

Peran

.env

Nilai yang berbeda per lingkungan, termasuk rahasia. Tidak di-commit

.env.example

Templat tanpa rahasia. Di-commit

config/*.php

Menentukan nilai bawaan dan membaca .env lewat env('KEY', 'default')

config('app.name')

Cara membaca konfigurasi di kode aplikasi

Aturan emas: panggil env() hanya di dalam folder config/. Di tempat lain, gunakan config().

2. Berkas .env Dasar

APP_NAME="Toko Saya"
APP_ENV=local
APP_KEY=base64:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=
APP_DEBUG=true
APP_URL=http://toko.test

APP_LOCALE=id
APP_FALLBACK_LOCALE=en
APP_FAKER_LOCALE=id_ID

LOG_CHANNEL=stack
LOG_LEVEL=debug

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=toko
DB_USERNAME=root
DB_PASSWORD=

SESSION_DRIVER=database
CACHE_STORE=database
QUEUE_CONNECTION=database

Aturan penulisan:

  • Nilai dengan spasi harus diapit tanda kutip: APP_NAME="Toko Saya".

  • Password dengan karakter khusus (#, $, spasi) sebaiknya diapit kutip: DB_PASSWORD="p#ss$word".

  • Referensi variabel: MAIL_FROM_NAME="${APP_NAME}".

  • Nilai true, false, null dan (empty) dikonversi otomatis oleh env().

3. Application Key (APP_KEY)

APP_KEY adalah kunci acak yang dipakai Laravel untuk mengenkripsi dan menandatangani data: cookie, session terenkripsi, hasil encrypt(), dan tautan bertanda tangan.

Membuat kunci:

php artisan key:generate
   INFO  Application key set successfully.

Perintah ini menulis APP_KEY ke .env. Untuk menampilkannya tanpa menulis:

php artisan key:generate --show

Hal yang harus dipahami:

Situasi

Akibat

APP_KEY kosong

Error No application encryption key has been specified

APP_KEY diganti saat aplikasi berjalan

Semua session aktif tidak valid, dan data terenkripsi (kolom encrypted, Crypt::encrypt) tidak bisa didekripsi

APP_KEY bocor

Penyerang bisa memalsukan cookie dan data terenkripsi. Ganti segera

Banyak server

Semua server harus memakai APP_KEY yang sama

Rotasi kunci tanpa memutus data lama, dengan APP_PREVIOUS_KEYS (tersedia sejak Laravel 11):

APP_KEY=base64:KUNCI_BARU...
APP_PREVIOUS_KEYS="base64:KUNCI_LAMA1...,base64:KUNCI_LAMA2..."

Laravel mengenkripsi dengan kunci baru, dan masih bisa membaca data dengan kunci lama. Setelah semua data terenkripsi ulang, hapus kunci lama.

4. Lingkungan dan Mode Debug

Variabel

Lokal

Production

APP_ENV

local

production

APP_DEBUG

true

false

LOG_LEVEL

debug

warning atau error

APP_DEBUG=true di production menampilkan stack trace dan isi konfigurasi kepada pengunjung. Itu celah keamanan serius.

Cek lingkungan di kode:

app()->environment('local');          // true/false
app()->isProduction();                // true/false

5. Konfigurasi Database

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=toko
DB_USERNAME=toko_user
DB_PASSWORD="GantiDenganPasswordKuat!"

Lihat konfigurasi yang aktif dan uji koneksi:

php artisan config:show database.default
php artisan db:show
php artisan migrate:status
  MySQL 8.4.x ........................................ toko
  Host ............................................ 127.0.0.1
  Port ................................................ 3306
  Tables ..................................................... 9

Detail koneksi MySQL dan MariaDB dibahas di artikel tersendiri.

6. Konfigurasi Cache, Session, dan Queue

Sejak Laravel 11, nama variabel cache adalah CACHE_STORE (sebelumnya CACHE_DRIVER).

Variabel

Pilihan umum

Catatan

CACHE_STORE

database, file, redis, array

array hanya untuk test

SESSION_DRIVER

database, file, redis, cookie

database adalah bawaan baru

QUEUE_CONNECTION

sync, database, redis

sync tidak berjalan di latar belakang

Konfigurasi untuk driver database (tabel sudah termasuk migrasi bawaan skeleton):

SESSION_DRIVER=database
CACHE_STORE=database
QUEUE_CONNECTION=database
php artisan migrate

Konfigurasi untuk Redis:

CACHE_STORE=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

REDIS_CLIENT=phpredis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

Uji cache:

php artisan tinker
> Cache::put('uji', 'halo', 60);
> Cache::get('uji');
= "halo"

7. Konfigurasi Zona Waktu dan Bahasa

Zona waktu diatur di config/app.php:

'timezone' => 'Asia/Jakarta',

Bahasa lewat .env:

APP_LOCALE=id
APP_FALLBACK_LOCALE=en

Sebaiknya simpan data waktu di database dalam UTC, dan konversi saat ditampilkan. Jika memilih menyimpan dalam waktu lokal, konsistenlah di seluruh aplikasi.

8. Konfigurasi Kustom Aplikasi

Buat berkas sendiri di config/, lalu baca dengan config():

// config/shop.php
return [
    'currency'        => 'IDR',
    'low_stock_limit' => (int) env('SHOP_LOW_STOCK_LIMIT', 5),
    'payment' => [
        'server_key'    => env('PAYMENT_SERVER_KEY'),
        'is_production' => (bool) env('PAYMENT_IS_PRODUCTION', false),
    ],
];
$limit = config('shop.low_stock_limit');
$key   = config('shop.payment.server_key');

Jangan menulis seperti ini di controller atau service:

$key = env('PAYMENT_SERVER_KEY');   // SALAH: akan bernilai null saat config di-cache

9. Cache Konfigurasi di Production

php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan event:cache
# atau sekaligus:
php artisan optimize

Setelah config:cache, Laravel tidak lagi membaca .env saat request, hanya berkas cache. Itulah sebab env() di luar config/ menjadi null, dan sebab perubahan .env tidak berefek sebelum cache dibersihkan.

php artisan config:clear      # hapus cache konfigurasi
php artisan optimize:clear    # hapus semua cache optimasi

Di lingkungan lokal, jangan meng-cache konfigurasi, agar perubahan .env langsung terbaca.

10. Mengelola .env per Lingkungan

Lingkungan

Cara

Lokal

.env pribadi tiap developer, dari .env.example

Testing

.env.testing atau phpunit.xml (DB_DATABASE, CACHE_STORE=array)

Staging/Production

.env di server, atau variabel lingkungan dari platform

Konfigurasi phpunit.xml agar test tidak menyentuh database asli:

<php>
    <env name="APP_ENV" value="testing"/>
    <env name="DB_CONNECTION" value="sqlite"/>
    <env name="DB_DATABASE" value=":memory:"/>
    <env name="CACHE_STORE" value="array"/>
    <env name="SESSION_DRIVER" value="array"/>
    <env name="QUEUE_CONNECTION" value="sync"/>
</php>

Untuk berbagi .env dengan tim secara aman, Laravel menyediakan enkripsi berkas:

php artisan env:encrypt --env=production
   INFO  Environment successfully encrypted.
  Key ........ base64:xxxxxxxx
  Cipher ..... AES-256-CBC
  Encrypted file .... .env.production.encrypted
php artisan env:decrypt --env=production --key=base64:xxxxxxxx

Berkas .env.production.encrypted boleh di-commit, tetapi kuncinya harus dikirim lewat kanal aman (password manager, secret manager CI), bukan di repository.

11. Memeriksa Konfigurasi yang Berlaku

php artisan about
php artisan config:show app
php artisan config:show cache
php artisan env
  Environment ..........................................
  Application Name ................................ Toko Saya
  Laravel Version ......................................... 13.x
  PHP Version ......................................... 8.3.x
  Environment ........................................... local
  Debug Mode ......................................... ENABLED
  URL ............................................. toko.test
  Cache .............................................. database
  Database ............................................. mysql
  Queue ............................................ database
  Session ........................................... database

Troubleshooting

Gejala

Penyebab

Solusi

No application encryption key has been specified

APP_KEY kosong

php artisan key:generate, lalu config:clear

Perubahan .env tidak berefek

Konfigurasi masih di-cache

php artisan config:clear

env('X') mengembalikan null di production

env() dipakai di luar config/ dan config di-cache

Pindahkan ke config/*.php, baca dengan config()

The MAC is invalid / Invalid payload

APP_KEY berubah, atau berbeda antar server

Samakan APP_KEY, atau gunakan APP_PREVIOUS_KEYS

SQLSTATE[HY000] [2002] Connection refused

MySQL mati, atau host/port salah

Jalankan MySQL, cek DB_HOST dan DB_PORT

SQLSTATE[HY000] [1045] Access denied

Username atau password salah

Cocokkan dengan akun database, beri tanda kutip pada password berkarakter khusus

SQLSTATE[HY000] [1049] Unknown database

Database belum dibuat

CREATE DATABASE ..., lalu php artisan migrate

Table 'sessions' doesn't exist

Driver database tanpa migrasi

php artisan migrate

Nilai .env terpotong di tanda #

# dianggap komentar

Apit nilai dengan tanda kutip

Nilai .env dengan spasi menyebabkan error

Tidak diberi kutip

APP_NAME="Toko Saya"

Test menghapus data asli

Test memakai database yang sama

Atur database khusus di phpunit.xml atau .env.testing

Please provide a valid cache path

storage/framework/cache atau views hilang

Buat folder storage/framework/{cache,sessions,views} dan atur izin

Best Practices

Keamanan

  • Jangan commit .env. Pastikan masuk .gitignore (sudah bawaan). Jika terlanjur ter-commit, anggap semua rahasianya bocor lalu ganti semuanya, bukan sekadar menghapus berkas.

  • Production: APP_DEBUG=false, APP_ENV=production, SESSION_SECURE_COOKIE=true bila memakai HTTPS.

  • Pakai akun database khusus aplikasi dengan hak terbatas, bukan root.

  • Simpan APP_KEY dan kredensial di password manager atau secret manager.

  • Jangan menaruh rahasia di config/*.php sebagai nilai bawaan literal.

Performa

  • Production: php artisan optimize pada setiap deploy.

  • Gunakan Redis untuk cache dan session pada aplikasi dengan trafik tinggi atau banyak server.

  • Gunakan LOG_LEVEL yang lebih tinggi di production agar log tidak membengkak.

Maintainability

  • Perbarui .env.example setiap menambah variabel baru, dengan nilai aman dan komentar.

  • Beri nilai bawaan yang masuk akal di config/*.php: env('SHOP_LOW_STOCK_LIMIT', 5).

  • Kelompokkan konfigurasi sendiri dalam satu berkas per domain (config/shop.php).

  • Tulis daftar variabel wajib di README.md.

  • Tambahkan pengecekan konfigurasi pada skrip deploy: php artisan about dan php artisan config:show.

Related Articles

Last Tested

Catatan jujur: disusun dari dokumentasi resmi Laravel (konfigurasi, enkripsi .env, rotasi kunci), tetapi belum dijalankan ulang di proyek nyata oleh penulis. Verifikasi nama variabel di berkas config/*.php pada versi Anda.

Komponen

Versi acuan penulisan

Versi saat Anda menguji

PHP

8.3.x

Laravel

13.x (kompatibel dengan 12.x)

MySQL

8.x

Redis (opsional)

7.x

Tanggal uji

Bagikan artikel:

Artikel lainnya