Mengelola Dependency Project dengan composer.json dan composer.lock

Saat kamu bekerja dalam tim atau memindahkan proyek aplikasi PHP dari lingkungan lokal (development) ke server internet (production), kamu akan sering menemui masalah klasik: "Di komputetku kodenya jalan, tapi di server kok error?"

Penyebab paling sering dari masalah tersebut adalah perbedaan versi pustaka (library/package) yang diinstal.

Di sinilah dua file krusial milik Composer mengambil peran: composer.json dan composer.lock. Meskipun terlihat mirip, keduanya memiliki fungsi yang sangat berbeda namun saling melengkapi. Mari kita bedah perbedaannya dan cara mengelolanya secara praktis!

1. Memahami Peran composer.json: Cetak Biru Kebutuhan Proyek

File composer.json adalah file konfigurasi utama berbentuk format JSON yang berisi daftar kebutuhan (dependencies) proyekmu beserta kisaran versi yang kamu izinkan untuk diinstal.

Anatomy File composer.json

Berikut adalah contoh isi file composer.json dalam proyek nyata:

JSON

{
    "name": "nama-vendor/nama-proyek",
    "description": "Aplikasi E-Commerce Sederhana",
    "type": "project",
    "require": {
        "php": "^8.1",
        "guzzlehttp/guzzle": "^7.5",
        "monolog/monolog": "^3.0"
    },
    "require-dev": {
        "phpunit/phpunit": "^10.0"
    },
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

Komponen Penting:

• require: Daftar pustaka wajib yang dibutuhkan aplikasi agar bisa berjalan di lingkungan production.

• require-dev: Pustaka yang hanya dibutuhkan saat proses pengembangan di komputer lokal (seperti pustaka testing phpunit atau debugging), dan tidak akan diikutkan saat di-deploy ke server live.

2. Memahami Simbol Versi (Semantic Versioning / Caret & Tilde)

Di dalam composer.json, kamu akan melihat nomor versi dengan simbol seperti ^7.5 atau ~2.1. Aturan penulisan versi ini mengikuti standar Semantic Versioning (MAJOR.MINOR.PATCH):

v2.4.1 $\rightarrow$ 2 = Major, 4 = Minor, 1 = Patch

• Patch: Perbaikan bug kecil (aman di-update).

• Minor: Penambahan fitur baru yang backwards-compatible (aman di-update).

• Major: Perubahan besar yang berisiko merusak kode lama (breaking changes).

Arti Simbol di Composer:

3. Memahami Peran composer.lock: Catatan Versi Absolut

Jika composer.json berisi kisaran versi yang kamu inginkan, maka composer.lock berisi catatan pasti versi spesifik dari seluruh pustaka yang benar-benar diunduh di dalam folder vendor/.

┌──────────────────────────┐
│      composer.json       │ ──► Berisi keinginan: "Saya mau Guzzle versi ^7.5"
└──────────────────────────┘
             │
             ▼ (Saat jalankan `composer install` / `composer update`)
┌──────────────────────────┐
│      composer.lock       │ ──► Berisi fakta pasti: "Versi terinstall persis 7.5.2"
└──────────────────────────┘

Mengapa composer.lock Sangat Penting?

Bayangkan kamu mengembangkan proyek hari ini dan Composer mengunduh Guzzle versi 7.5.0. Enam bulan kemudian, rekan timmu mengkloning proyek tersebut. Jika tidak ada file composer.lock, Composer akan mengunduh versi terbaru (misal 7.8.1).

Meskipun versi minor seharusnya aman, terkadang ada perubahan perilaku yang membuat aplikasi rekan timmu tidak berjalan sama seperti di komputermu.

Dengan adanya composer.lock, siapapun yang mengunduh proyekmu akan mendapatkan versi pustaka yang 100% identik hingga ke bit terkecilnya!

4. Perbedaan Vital: composer install vs composer update

Banyak pemula salah memahami penggunaan dua perintah terminal ini. Memilih perintah yang salah bisa merusak build aplikasi di server!

               [Perintah Composer yang Dijalankan]
                                │
                  Apakah file composer.lock ada?
                   ╱                          ╲
                 Ya                            Tidak
                 ╱                              ╲
     ┌───────────────────────┐      ┌──────────────────────────┐
     │   composer install    │      │     composer update      │
     │ Baca composer.lock &  │      │ Baca composer.json, cari │
     │ install versi PERSIS! │      │ versi TERBARU, lalu buat │
     └───────────────────────┘      │ file composer.lock baru! │
                                    └──────────────────────────┘

A. Perintah composer install

• Prinsip Utama: Mementingkan Konsistensi.

• Cara Kerja: Composer membaca file composer.lock. Composer TIDAK AKAN mencari versi baru di internet, melainkan mengunduh versi yang persis dicatat di file .lock.

• Kapan Digunakan?

  • Saat pertama kali mengkloning proyek dari Git.

  • Saat proses deployment otomatis ke server production.

  • Ketika rekan tim baru akan mulai koding di proyek yang sama.

B. Perintah composer update

• Prinsip Utama: Mementingkan Pembaruan (Upgrade).

• Cara Kerja: Composer mengabaikan file composer.lock, lalu membaca aturan di composer.json. Composer mencari versi pustaka terbaru di internet yang masih sesuai dengan batasan simbol (misal ^7.5), mengunduhnya, lalu memperbarui file composer.lock.

• Kapan Digunakan?

  • Ketika kamu secara sengaja ingin memperbarui pustaka ke versi terbaru untuk mendapatkan fitur baru atau perbaikan celah keamanan (security patch).

  • Peringatan: Jalankan composer update hanya di komputer lokal, lakukan testing, lalu commit file composer.lock yang baru ke Git!

5. Aturan Git & Best Practices

Agar pengelolaan dependensi di timmu berjalan lancar, patuhi aturan emas Git berikut:

1. WAJIB Commit composer.json dan composer.lock ke dalam repository (Git). Ini menjamin seluruh tim dan server memiliki environment yang identik.

2. HARAM Commit folder vendor/ ke Git. Masukkan folder vendor/ ke dalam file .gitignore. Mengapa? Karena file di dalam vendor/ sangat besar dan bisa diunduh kapan saja secara otomatis menggunakan perintah composer install.

Kesimpulan

Memahami perbedaan antara composer.json (rencana kebutuhan) dan composer.lock (eksekusi riil) adalah kunci utama menjaga stabilitas aplikasi PHP modern.

Dengan menggunakan composer install di server production, kamu terbebas dari ancaman perbedaan versi pustaka yang bisa merusak sistem.