Laravel .env: Cara Kerja Environment Variable dan Kesalahan yang Sering Terjadi

File .env adalah salah satu bagian penting dalam aplikasi Laravel. Di dalamnya biasanya tersimpan berbagai konfigurasi yang berbeda antara lingkungan development, testing, dan production, seperti koneksi database, application key, cache, mail server, hingga konfigurasi layanan pihak ketiga.

Namun, banyak masalah Laravel yang sebenarnya bukan berasal dari kode aplikasi, melainkan dari cara .env dan configuration system bekerja.

Memahami mekanismenya akan membuat proses debugging jauh lebih mudah.

Apa Itu File .env di Laravel?

.env adalah file yang digunakan untuk menyimpan environment variable, yaitu nilai konfigurasi yang dapat berubah tergantung lingkungan tempat aplikasi dijalankan.

Contoh sederhana:

APP_NAME="My Laravel App"
APP_ENV=local
APP_DEBUG=true

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

Daripada menulis konfigurasi tersebut langsung di dalam source code, Laravel mengambil nilainya dari environment.

Pendekatan ini memiliki beberapa keuntungan:

• Konfigurasi development dan production dapat dibuat berbeda.
• Credential tidak perlu ditulis langsung di source code.
• Deployment menjadi lebih fleksibel.
• Konfigurasi layanan eksternal dapat diganti tanpa mengubah kode aplikasi.

Bagaimana Laravel Membaca .env?

Secara sederhana, alurnya dapat dipahami seperti ini:

.env
  ↓
Environment Variable
  ↓
config/*.php
  ↓
Aplikasi Laravel

File .env bukan berarti setiap bagian aplikasi Laravel membaca file tersebut secara langsung.

Laravel menggunakan environment variable tersebut sebagai sumber konfigurasi. File di dalam direktori config kemudian biasanya mengambil nilainya menggunakan fungsi env().

Contohnya:

// config/app.php

'debug' => (bool) env('APP_DEBUG', false),

Untuk database:

// config/database.php

'connections' => [
    'mysql' => [
        'driver' => 'mysql',
        'host' => env('DB_HOST', '127.0.0.1'),
        'port' => env('DB_PORT', '3306'),
        'database' => env('DB_DATABASE', 'laravel'),
        'username' => env('DB_USERNAME', 'root'),
        'password' => env('DB_PASSWORD', ''),
    ],
],

Jadi ketika aplikasi membutuhkan konfigurasi database, Laravel tidak harus membaca .env secara langsung dari setiap bagian kode.

Kenapa env() Sebaiknya Tidak Dipakai Sembarangan?

Salah satu kesalahan yang sering terjadi adalah menggunakan env() langsung di dalam kode aplikasi.

Misalnya:

class PaymentService
{
    public function process()
    {
        $key = env('PAYMENT_API_KEY');

        // ...
    }
}

Sekilas kode tersebut terlihat benar. Namun, Laravel memiliki configuration caching yang membuat penggunaan env() di luar file konfigurasi menjadi bermasalah.

Praktik yang lebih baik adalah memasukkan environment variable ke file konfigurasi terlebih dahulu.

// config/services.php

'payment' => [
    'key' => env('PAYMENT_API_KEY'),
],

Kemudian aplikasi mengambil konfigurasi melalui:

$key = config('services.payment.key');

Dengan pola ini, konfigurasi aplikasi menjadi lebih konsisten dan kompatibel dengan configuration cache.

Kesalahan Umum: .env Sudah Diubah, tetapi Aplikasi Tidak Berubah

Ini adalah salah satu masalah Laravel yang paling sering membingungkan.

Misalnya Anda mengubah:

APP_DEBUG=false

tetapi aplikasi masih menunjukkan konfigurasi lama.

Kemungkinan besar konfigurasi Laravel sedang menggunakan configuration cache.

Anda dapat membersihkannya dengan:

php artisan config:clear

Jika ingin membangun ulang configuration cache:

php artisan config:cache

Untuk development, penting memahami bahwa perubahan .env tidak selalu langsung terlihat apabila konfigurasi sebelumnya sudah di-cache.

config:cache dan Hubungannya dengan .env

Ketika menjalankan:

php artisan config:cache

Laravel menggabungkan konfigurasi aplikasi menjadi cache sehingga proses membaca konfigurasi dapat dilakukan dengan lebih efisien.

Karena itu, setelah konfigurasi di-cache, jangan mengandalkan pembacaan .env secara langsung di dalam class aplikasi.

Gunakan:

config('services.payment.key')

bukan:

env('PAYMENT_API_KEY')

untuk kode aplikasi.

Pola sederhananya:

.env
 ↓
config/*.php
 ↓
config(...)
 ↓
Application

Kesalahan Umum: Salah Menulis Nilai Boolean

Environment variable pada dasarnya berupa nilai teks. Karena itu, penulisan boolean perlu diperhatikan.

Contoh:

APP_DEBUG=true

dan:

APP_DEBUG=false

Berbeda dengan menulis nilai secara sembarangan seperti:

APP_DEBUG=False

Laravel memiliki mekanisme parsing environment tertentu, tetapi praktik terbaiknya adalah mengikuti format yang konsisten dan sederhana.

Untuk nilai boolean, gunakan:

true

atau:

false

Kesalahan Umum: Nilai yang Mengandung Spasi

Jika sebuah nilai mengandung spasi, gunakan tanda kutip.

Contohnya:

APP_NAME="My Laravel Application"

Tanpa tanda kutip, nilai tersebut dapat diproses secara tidak sesuai dengan yang Anda harapkan.

Hal yang sama perlu diperhatikan untuk nilai yang memiliki karakter khusus atau format tertentu.

Kesalahan Umum: Lupa Membuat .env

Dalam repository Laravel, file .env biasanya tidak disimpan ke Git karena dapat berisi credential dan konfigurasi yang bersifat sensitif.

Sebagai gantinya, Laravel menyediakan file:

.env.example

Ketika melakukan setup project baru, developer biasanya membuat .env berdasarkan file tersebut.

Contoh:

cp .env.example .env

Setelah itu, sesuaikan konfigurasi dengan environment lokal.

Jangan Menyimpan Credential Sensitif ke Repository

Salah satu alasan utama .env tidak seharusnya dimasukkan ke repository publik adalah karena file tersebut dapat berisi informasi sensitif seperti:

DB_PASSWORD=super-secret-password

atau:

AWS_SECRET_ACCESS_KEY=...

atau:

STRIPE_SECRET=...

Jika credential tersebut masuk ke repository, menghapus file dari commit terbaru belum tentu cukup. Credential yang sudah pernah terpublikasi sebaiknya dianggap telah bocor dan segera dirotasi.

.gitignore Laravel biasanya sudah mengatur .env agar tidak ikut ter-commit.

Tetap periksa konfigurasi repository Anda, terutama jika project berasal dari template atau konfigurasi custom.

.env Bukan Tempat untuk Semua Konfigurasi

Meskipun .env sangat berguna, bukan berarti seluruh konfigurasi aplikasi harus dimasukkan ke sana.

Gunakan .env untuk nilai yang memang bergantung pada environment.

Contohnya:

APP_ENV=production
DB_HOST=database.internal
CACHE_STORE=redis
MAIL_HOST=smtp.example.com

Sedangkan struktur konfigurasi sebaiknya tetap berada di file config.

Misalnya:

// config/services.php

'payment' => [
    'key' => env('PAYMENT_API_KEY'),
    'timeout' => 30,
],

Dengan begitu, environment variable menyediakan nilai yang dapat berubah, sementara file konfigurasi menentukan struktur dan cara aplikasi menggunakan nilai tersebut.

Kesalahan Umum: Mengira .env Hanya Berlaku di Localhost

.env bukan fitur khusus untuk local development.

Konsep environment variable digunakan di berbagai environment:

Development
    ↓
.env lokal

Testing
    ↓
Testing environment

Production
    ↓
Server/container/platform environment

Di production, environment variable bahkan sering disediakan langsung oleh server, container, cloud platform, atau deployment system tanpa perlu menyimpan file .env secara fisik di repository.

Karena itu, aplikasi Laravel sebaiknya dirancang agar konfigurasi environment dapat diberikan secara fleksibel.

Kesalahan Umum: Mengubah .env di Production Tanpa Memahami Cache

Misalnya production memiliki:

APP_ENV=production
APP_DEBUG=false

Kemudian Anda mengubah nilai .env tetapi aplikasi tetap menggunakan konfigurasi lama.

Jangan langsung menyimpulkan bahwa Laravel gagal membaca .env.

Periksa configuration cache terlebih dahulu:

php artisan config:show app

Anda juga dapat membersihkan cache konfigurasi jika memang diperlukan:

php artisan config:clear

Setelah itu, jika deployment menggunakan configuration cache, build ulang cache:

php artisan config:cache

Pada production, proses ini sebaiknya menjadi bagian dari prosedur deployment agar perubahan konfigurasi diterapkan secara konsisten.

Kesalahan Umum: .env Berbeda dengan .env.example

File .env.example sebaiknya berfungsi sebagai dokumentasi konfigurasi yang dibutuhkan aplikasi.

Misalnya .env.example memiliki:

APP_NAME=
APP_ENV=
APP_KEY=

DB_CONNECTION=
DB_HOST=
DB_PORT=
DB_DATABASE=
DB_USERNAME=
DB_PASSWORD=

PAYMENT_API_KEY=

Sementara .env lokal berisi nilai sebenarnya.

Dengan begitu, developer baru dapat mengetahui environment variable apa saja yang diperlukan tanpa harus meminta isi credential dari developer lain.

Yang perlu diperhatikan: jangan menaruh secret asli di .env.example.

Gunakan placeholder:

PAYMENT_API_KEY=

bukan:

PAYMENT_API_KEY=sk-live-real-secret

Cara Debugging Masalah .env

Ketika konfigurasi tidak bekerja, jangan langsung mengubah banyak file sekaligus.

Gunakan pendekatan bertahap.

1. Periksa nama variable

Pastikan:

DB_DATABASE=my_database

benar-benar sama dengan:

env('DB_DATABASE')

Kesalahan kecil seperti:

DB_DATABASE=my_database

tetapi kode mencari:

env('DATABASE_NAME')

akan menghasilkan konfigurasi yang berbeda.

2. Periksa file konfigurasi

Cari apakah variable tersebut digunakan di:

config/app.php
config/database.php
config/cache.php
config/mail.php
config/services.php

atau file konfigurasi custom lainnya.

3. Periksa configuration cache

Jika nilai terasa tidak mengikuti .env terbaru, jalankan:

php artisan config:clear

Kemudian cek kembali aplikasi.

4. Periksa environment variable yang benar-benar digunakan aplikasi

Daripada menebak, lihat konfigurasi Laravel:

php artisan config:show database

atau:

php artisan config:show app

Ini dapat membantu mengetahui nilai konfigurasi yang sedang digunakan.

5. Jangan mencetak secret ke log

Hindari debugging seperti:

dd(env('DB_PASSWORD'));

terutama pada environment yang dapat diakses orang lain.

Untuk secret, cukup periksa apakah konfigurasi tersedia tanpa menampilkan nilainya secara langsung.

Pola yang Direkomendasikan

Untuk aplikasi Laravel, pola yang sederhana dan aman adalah:

Environment
    ↓
.env / platform environment variables
    ↓
config/*.php
    ↓
config()
    ↓
Application

Contoh:

PAYMENT_API_KEY=secret-value

Kemudian:

// config/services.php

'payment' => [
    'key' => env('PAYMENT_API_KEY'),
],

Dan di aplikasi:

$key = config('services.payment.key');

Dengan pola tersebut, kode aplikasi tidak perlu mengetahui dari mana konfigurasi berasal.

Kesimpulan

.env memang terlihat seperti file sederhana, tetapi perannya cukup penting dalam arsitektur aplikasi Laravel.

Hal utama yang perlu diingat:

• .env menyimpan nilai konfigurasi yang bergantung pada environment.
• File config/*.php menjadi lapisan konfigurasi aplikasi.
• Gunakan env() terutama di file konfigurasi.
• Gunakan config() ketika membaca konfigurasi dari kode aplikasi.
• Configuration cache dapat membuat perubahan .env tidak langsung terlihat.
• Jangan memasukkan credential sensitif ke repository.
• Gunakan .env.example sebagai template konfigurasi tanpa secret asli.
• Saat debugging, periksa variable, file konfigurasi, dan cache secara berurutan.

Memahami hubungan antara .env, config/*.php, dan config() akan menghindarkan Anda dari banyak masalah Laravel yang awalnya terlihat seperti bug pada aplikasi, padahal sebenarnya hanya masalah konfigurasi.