composer.json

Setiap proyek yang dikelola Composer memiliki satu berkas pusat kendali bernama composer.json, diletakkan di akar (root) proyek. Berkas ini adalah manifesto: seluruh kebutuhan proyek — dependensi produksi, dependensi pengembangan, peta autoload, sampai perintah pintasan — dinyatakan di dalamnya. Mesin membaca berkas ini untuk menghitung apa yang harus dipasang, sementara manusia membacanya untuk memahami proyek dalam hitungan detik. Pada chapter ini kita membedah anatomi composer.json field demi field, membuktikan bahwa berkas tersebut hanyalah JSON biasa yang bisa dibaca dari dalam PHP, lalu menutup dengan cara memvalidasinya.

Anatomi Sebuah composer.json #

Berikut contoh composer.json yang realistis untuk sebuah aplikasi toko online. Kita akan gunakan contoh yang sama ini sebagai contoh berjalan sepanjang section:

{
    "name": "budi/toko-online",
    "description": "Aplikasi toko online untuk belajar Composer",
    "type": "project",
    "license": "MIT",
    "require": {
        "php": ">=8.1",
        "ext-json": "*",
        "monolog/monolog": "^3.7"
    },
    "require-dev": {
        "phpstan/phpstan": "^2.0"
    },
    "autoload": {
        "psr-4": {
            "Toko\\": "src/"
        }
    },
    "scripts": {
        "test": "phpunit --colors=always",
        "analyse": "phpstan analyse src --level=8"
    },
    "config": {
        "optimize-autoloader": true
    },
    "minimum-stability": "stable",
    "prefer-stable": true
}

Tabel berikut merangkum peran setiap field sebelum kita bedah yang terpenting:

require dan require-dev #

Field require mendaftarkan paket yang harus terpasang agar aplikasi berjalan di server produksi. Setiap entri berformat "nama-paket": "kendala-versi" — misalnya "monolog/monolog": "^3.7" berarti versi 3.7 ke atas selama masih di major version 3. Dua entri pertama pada contoh kita bukan paket dari Packagist, melainkan platform package: php dan ext-json memeriksa lingkungan itu sendiri. Composer akan menolak memasang dependensi apabila versi PHP runtime atau ekstensi JSON di mesin tidak memenuhi syarat tersebut.

Field require-dev menampung paket yang hanya dibutuhkan selama pengembangan — penganalisis statis phpstan pada contoh kita. Paket dalam require-dev tidak ikut dipasang ketika deployment produksi dijalankan dengan opsi --no-dev, sehingga server produksi tetap ramping. Pemisahan ini juga penting bagi library: pengguna library Anda tidak perlu ikut memasang perkakas pengujian Anda.

Autoload PSR-4 #

Field autoload memberi tahu Composer di mana menemukan class milik proyek sendiri. Aturan "Toko\\": "src/" berarti namespace Toko\ dipetakan ke folder src/, sehingga class Toko\Util\Keranjang dicari di berkas src/Util/Keranjang.php. Standar pemetaan ini disebut PSR-4 dan menjadi tulang punggung autoloader yang dihasilkan Composer. Kita bedah mekanismenya secara menyeluruh pada chapter autoloading dengan Composer .

Scripts dan Konfigurasi Perilaku #

Field scripts mendefinisikan perintah pintasan: setelah dependensi terpasang, composer test menjalankan PHPUnit dan composer analyse menjalankan phpstan tanpa kita perlu mengingat argumen lengkapnya. Field config mengatur perilaku Composer sendiri — optimize-autoloader: true meminta Composer membangun autoloader kelas cepat yang sesuai untuk produksi. Terakhir, minimum-stability menentukan versi prarilis seperti alpha atau beta boleh dipilih atau tidak, sementara prefer-stable menyuruh Composer tetap memilih versi stabil bila ada; keduanya dibahas tuntas pada chapter version constraints .

Manifesto Hanyalah JSON Biasa #

Karena composer.json berformat JSON standar, berkas tersebut dapat dibaca dan diperiksa dari dalam PHP itu sendiri. Kemampuan ini berguna, misalnya, untuk menampilkan daftar dependensi di halaman administrasi atau membangun perkakas internal. Mari kita buktikan dengan mem-parsing salinan manifesto toko online di atas:

<?php
$json = <<<'JSON'
{
    "name": "budi/toko-online",
    "description": "Aplikasi toko online untuk belajar Composer",
    "type": "project",
    "license": "MIT",
    "require": {
        "php": ">=8.1",
        "ext-json": "*",
        "monolog/monolog": "^3.7"
    },
    "require-dev": {
        "phpstan/phpstan": "^2.0"
    },
    "autoload": {
        "psr-4": {
            "Toko\\": "src/"
        }
    }
}
JSON;
$manifest = json_decode($json, true);

echo "Proyek: {$manifest['name']}\n";
echo "Dependensi produksi: " . count($manifest['require']) . " paket\n";
echo "Dependensi pengembangan: " . count($manifest['require-dev']) . " paket\n";
echo "Namespace PSR-4: " . key($manifest['autoload']['psr-4']) . "\n";

Output yang Dihasilkan:

Proyek: budi/toko-online
Dependensi produksi: 3 paket
Dependensi pengembangan: 1 paket
Namespace PSR-4: Toko\

Mari kita telaah kode di atas:

1. Baris 2-20: salinan manifesto disimpan dalam nowdoc <<<'JSON' — tanda kutip tunggal pada penanda membuat seluruh isi diperlakukan apa adanya tanpa interpolasi variabel.
2. Baris 21: json_decode($json, true) mengubah teks JSON menjadi array asosiatif PHP bertingkat.
3. Baris 23-26: nilai-nilai dibaca seperti array biasa: count() menghitung entri dependensi, dan key() mengambil kunci pertama dari peta PSR-4, yaitu string Toko\.

Menulis Manual atau composer init #

Ada dua cara menghasilkan composer.json: menulis manual dengan editor teks, atau memakai perintah composer init yang mengajukan serangkaian pertanyaan interaktif. Berikut hasil composer init pada mode non-interaktif dengan semua jawaban diberikan lewat opsi:

cd init-banding
composer init --no-interaction --name budi/contoh-init --description "Contoh hasil composer init" --author "Budi Santoso <[email protected]>" --license MIT

Output yang Dihasilkan:

Writing ./composer.json

Berkas composer.json yang dihasilkan berisi kerangka minimal berikut:

{
    "name": "budi/contoh-init",
    "description": "Contoh hasil composer init",
    "license": "MIT",
    "authors": [
        {
            "name": "Budi Santoso",
            "email": "[email protected]"
        }
    ],
    "require": {}
}

composer init nyaman untuk proyek baru karena mengumpulkan identitas dasar (nama, deskripsi, penulis, lisensi) dalam satu dialog; field lain tinggal ditambahkan seiring kebutuhan. Menulis manual memberi kendali penuh dan cocok saat Anda sudah tahu persis isi manifestonya, atau saat menyalin pola dari proyek lain. Keduanya menghasilkan berkas yang setara — pilih sesuai selera, bukan sesuai kewajiban.

Memvalidasi dengan composer validate #

Entah ditulis manual atau lewat init, manifesto wajib diperiksa sebelum dipercaya. Perintah composer validate mencocokkan struktur berkas dengan skema resmi dan melaporkan field yang salah ketik, format versi yang tidak valid, atau nilai yang tidak masuk akal:

cd toko-manifest
composer validate

Output yang Dihasilkan:

./composer.json is valid

Satu baris is valid berarti seluruh field lolos pemeriksaan skema. Apabila ada kesalahan — misalnya nama field salah tulis atau kendala versi rusak — Composer mencetak daftar masalah beserta barisnya dan perintah berakhir dengan exit code bukan nol. Perilaku inilah yang membuat composer validate (dengan opsi --strict agar peringatan pun dianggap gagal) cocok dijalankan otomatis di CI sebagai penjaga mutu manifesto.

Dengan manifesto yang valid, pertanyaan berikutnya segera muncul: versi berapa persisnya yang dipasang Composer dari kendala ^3.7, dan bagaimana memastikan rekan satu tim mendapatkan versi yang sama? Jawabannya ada pada berkas pasangan composer.json — composer.lock, topik chapter berikutnya.

Referensi #

• The composer.json Schema — getcomposer.org
• Command line interface — getcomposer.org
• Basic usage — getcomposer.org