Konfigurasi dan env

Setiap nilai yang berbeda antara lingkungan pengembangan, pengujian, dan produksi dikelola Laravel melalui dua lapis berkas, yaitu .env untuk nilai khas mesin dan direktori config/ untuk definisi konfigurasi aplikasi. Topik ini membahas isi dan disiplin berkas .env, cara berkas config/ membacanya, pembacaan konfigurasi dari kode, serta caching konfigurasi untuk produksi. Setiap perintahnya diverifikasi pada proyek contoh.

Berkas .env dan konvensinya#

Berkas .env berada di akar proyek dan memuat pasangan KUNCI=nilai satu per baris. Berkas ini diabaikan oleh git pada proyek baru, karena isinya khas setiap mesin dan dapat memuat rahasia seperti kredensial database. Contoh potongan .env aplikasi contoh adalah sebagai berikut.

APP_NAME="Aplikasi Catatan"
APP_ENV=local
APP_KEY=base64:diisi-saat-proyek-dibuat
APP_DEBUG=true
APP_URL=http://localhost:8000

DB_CONNECTION=sqlite

SESSION_DRIVER=database

Nilai APP_ENV=local menandai lingkungan pengembangan, APP_DEBUG=true mengaktifkan halaman error terperinci, dan APP_KEY diisi kunci enkripsi otomatis saat composer create-project dijalankan. Apabila proyek didistribusikan, berkas .env.example yang menyertai proyek menjadi templat. Berkas itu digunakan sebagai titik awal .env baru tanpa membocorkan nilai rahasia mesin lain.

Lapisan config dan fungsi env()#

Direktori config/ berisi satu berkas PHP per subsistem, seperti config/app.php, config/database.php, dan config/session.php. Setiap berkas mengembalikan array, dan nilai khas mesin diambil dari fungsi env() dengan nilai baku sebagai argumen kedua. Bagian config/app.php memuat baris semacam 'name' => env('APP_NAME', 'Laravel'), sehingga apabila .env tidak mendefinisikan APP_NAME, nilai baku Laravel yang digunakan.

Rantai pembacaan ini menegaskan pembagian peran. .env menyimpan nilai, sedangkan config/ mendeklarasikan struktur dan nilai baku. Kode aplikasi tidak pernah memanggil env() secara langsung, melainkan memanggil config('app.name') dengan notasi titik berupa nama berkas diikuti kuncinya. Verifikasi pembacaan itu pada proyek contoh.

cd ~/aplikasi-catatan
# baca nilai konfigurasi timezone dari config/app.php
php artisan tinker --execute='echo config("app.timezone");'

UTC

Nilai UTC berasal dari baris 'timezone' => 'UTC' pada config/app.php. Nama aplikasi dibaca dengan notasi titik yang sama.

cd ~/aplikasi-catatan
# baca nama aplikasi dari config/app.php
php artisan tinker --execute='echo config("app.name");'

Laravel

Ringkasan kondisi lingkungan aplikasi dapat diperiksa dengan perintah about, yang membaca konfigurasi yang sama. Lebar tabelnya menyesuaikan terminal, sehingga perintah ini ditandai tidak-dijalankan pada verifikasi otomatis dan keluarannya diambil dari eksekusi nyata pada terminal dengan lebar 120 kolom.

# tidak-dijalankan
cd ~/aplikasi-catatan
# tampilkan ringkasan lingkungan aplikasi
php artisan about --only=environment

Hasil eksekusinya memuat nama aplikasi, versi framework, mode debug, URL, dan zona waktu yang sedang berlaku.

  Environment ............................................................
  Application Name ................................................... Laravel
  Laravel Version .................................................... 13.39.0
  PHP Version ......................................................... 8.3.29
  Composer Version .................................................... 2.11.1
  Environment .......................................................... local
  Debug Mode ......................................................... ENABLED
  URL ......................................................... localhost:8000
  Maintenance Mode ....................................................... OFF
  Timezone ............................................................... UTC
  Locale .................................................................. en

Tabel tersebut memperlihatkan nilai yang berlaku saat ini, seperti nama aplikasi yang masih bernilai baku Laravel dan Environment bernilai local dari .env. Perintah config:show menampilkan isi satu kelompok konfigurasi secara lebih rinci, misalnya php artisan config:show app.name untuk satu kunci saja.

Disiplin: config() alih-alih env()#

Panggilan env() hanya sah di dalam direktori config/. Alasannya ada pada mekanisme caching konfigurasi. Saat config:cache dijalankan, seluruh isi config/ digabung menjadi satu berkas PHP, dan pada titik itu berkas .env tidak dibaca lagi, sehingga setiap panggilan env() di luar config/ mengembalikan null. Aplikasi yang menjalankan config:cache di produksi kemudian memanggil env() dari controller akan membaca null dan berperilaku tidak terduga.

Konsekuensi praktisnya sederhana. Nilai khusus lingkungan dideklarasikan sebagai kunci baru pada berkas config/ yang membungkus env(), lalu kode aplikasi membaca kunci tersebut melalui config().

Caching konfigurasi untuk produksi#

Perintah config:cache menggabungkan semua berkas config/ beserta nilai env()-nya menjadi satu berkas cache, sehingga setiap permintaan tidak membaca belasan berkas konfigurasi lagi. Pasangannya adalah config:clear yang menghapus cache dan mengembalikan pembacaan berkas biasa. Keduanya dijalankan berurutan pada contoh berikut.

cd ~/aplikasi-catatan
# gabungkan konfigurasi menjadi satu berkas cache
php artisan config:cache
# hapus kembali cache konfigurasi
php artisan config:clear

   INFO  Configuration cached successfully.


   INFO  Configuration cache cleared successfully.

Pada produksi, config:cache termasuk langkah baku setiap kali rilis diterapkan, bersama caching rute dan tampilan. Pada lingkungan pengembangan, caching konfigurasi justru sering mengganggu karena perubahan .env hanya terlihat setelah cache dibangun ulang, sehingga kebiasaan yang lazim adalah membiarkan konfigurasi tanpa cache selama pengembangan.

Kesalahan umum#

Kesalahan pertama adalah memanggil env() dari controller atau service, sebagaimana dijelaskan pada bagian sebelumnya. Gejalanya berupa nilai null yang muncul hanya di server produksi dan tidak muncul di mesin pengembangan karena cache belum aktif di sana.

Kesalahan kedua adalah membiarkan APP_DEBUG=true di produksi. Halaman error yang terperinci ikut menampilkan potongan kode, variabel lingkungan, dan kredensial yang berada dalam memori permintaan, sehingga nilai itu wajib diubah menjadi false di server publik.

Kesalahan ketiga adalah menuliskan nilai lingkungan langsung ke berkas config/, misalnya mengganti 'timezone' => 'UTC' dengan zona waktu spesifik tanpa env(). Nilai tersebut kemudian sama untuk semua lingkungan dan tidak dapat diubah tanpa menyunting kode. Pola yang benar adalah tetap membungkusnya dengan env('APP_TIMEZONE', 'UTC') dan menetapkan nilainya di .env mesin terkait.

Kesalahan keempat adalah menyimpan nilai rahasia seperti kunci layanan pihak ketiga langsung di berkas konfigurasi. Berkas config/ masuk ke repository dan ikut terbaca oleh seluruh anggota tim maupun sistem penyebaran, sedangkan .env dikecualikan dari repository justru untuk menampung nilai semacam itu. Apabila sebuah kunci layanan perlu dibaca aplikasi, tempatnya adalah .env pada setiap mesin, dan direktori config/ hanya memuat pembungkus env()-nya.

Ringkasan#

• Konfigurasi terbagi dua lapis: .env menyimpan nilai khas mesin dan tidak masuk repository, sedangkan direktori config/ mendefinisikan struktur dan nilai baku melalui env().
• Kode aplikasi membaca konfigurasi melalui config('berkas.kunci'), dan env() hanya sah di dalam direktori config/.
• config:cache menggabungkan seluruh konfigurasi menjadi satu berkas dan membuat env() di luar config/ mengembalikan null, sehingga wajib dikawal disiplin config().
• Nilai khusus lingkungan baru ditambahkan dengan pola env() di config/ beserta nilainya di .env, bukan dengan menyunting berkas konfigurasi.

Referensi#

• Configuration — Laravel — Dokumentasi resmi konfigurasi Laravel yang menjadi dasar pembahasan berkas .env, env(), config:show, dan config:cache pada topik ini.