Composer ile PHP bağımlılık yönetimi: install mı update mi, lock dosyası neden önemli?

Eskiden bir PHP projesine kütüphane eklemek, bir zip dosyası indirip lib/ klasörüne açmak demekti. Hangi sürümün kullanıldığını kimse bilmezdi. Güncelleme yapmak ise her şeyin bozulabileceği bir maceraydı. Composer bu sorunu çözdü ve bugün neredeyse her modern PHP projesinin temelinde duruyor.

İki dosya, iki farklı görev

composer.json: Sizin isteğiniz. "Bu projenin şu paketlere, şu sürüm aralıklarında ihtiyacı var."

{
    "require": {
        "php": "^8.2",
        "guzzlehttp/guzzle": "^7.8",
        "monolog/monolog": "^3.5"
    },
    "require-dev": {
        "phpunit/phpunit": "^11.0"
    }
}

composer.lock: Gerçekte kurulan şey. "Bu aralıklardan şu anda tam olarak şu sürümler seçildi: guzzle 7.9.2, monolog 3.7.0..." Ayrıca bu paketlerin bağımlılıklarının da tam sürümlerini içerir.

Sürüm kısıtlarını okumak

• ^7.8 → 7.8.0 ve üstü, ama 8.0.0'dan küçük. Anlamsal sürümlemede (semver) büyük sürüm değişmediği sürece geriye dönük uyumluluk beklenir. En yaygın kullanılan kısıt budur.
• ~7.8 → 7.8.0 ve üstü, ama 7.9.0'dan küçük. Daha kısıtlayıcıdır.
• 7.8.* → 7.8 serisindeki herhangi bir sürüm.
• >=7.8 <8.0 → açıkça yazılmış aralık.
• 7.8.1 → yalnızca bu sürüm. Güvenlik yamalarını da engellediği için genellikle tavsiye edilmez.

Bir uyarı: ^0.3 gibi 0 ile başlayan sürümlerde semver farklı yorumlanır. ^0.3, 0.3.x anlamına gelir ve 0.4'ü kapsamaz, çünkü 0.x sürümlerinde her küçük sürüm kırıcı değişiklik içerebilir.

install ve update farkı

En çok karıştırılan konu budur.

composer install: Lock dosyası varsa, tam olarak orada yazan sürümleri kurar. Hiçbir şeyi güncellemez. Lock dosyası yoksa composer.json'a göre çözüm yapar ve yeni bir lock dosyası oluşturur.

composer update: composer.json'daki aralıklara göre en yeni uygun sürümleri arar, kurar ve lock dosyasını yeniden yazar.

Buradan çıkan altın kural şudur:

• Geliştirme ortamında bilinçli olarak composer update çalıştırırsınız, testleri koşarsınız ve değişen lock dosyasını commit edersiniz.
• Canlı sunucuda ve CI ortamında yalnızca composer install çalıştırırsınız.

Canlı sunucuda update çalıştırmak, test etmediğiniz sürümleri doğrudan yayına almak demektir.

Lock dosyası depoya girer

Uygulama projelerinde composer.lock mutlaka depoya commit edilmelidir. Aksi hâlde aynı kodu bugün kuran geliştirici ile üç ay sonra kuran sunucu, farklı paket sürümleriyle çalışır. "Bende çalışıyordu" sorununun en sinsi biçimlerinden biri budur.

İstisna: Başkalarının kullanması için yazdığınız bir kütüphane geliştiriyorsanız, lock dosyası kullanıcıları etkilemez. Ama kendi testlerinizin tutarlılığı için yine de tutulabilir.

Canlı ortama doğru kurulum

composer install --no-dev --optimize-autoloader --no-interaction

• --no-dev: PHPUnit gibi geliştirme paketlerini kurmaz. Hem yer kazandırır hem de saldırı yüzeyini küçültür.
• --optimize-autoloader: Sınıf haritasını önceden oluşturur ve otomatik yüklemeyi hızlandırır.

vendor/ klasörü depoya girmez. .gitignore dosyasına ekleyin ve her ortamda install ile oluşturun.

Tek bir paketi güncellemek

Bütün paketleri bir anda güncellemek yerine:

composer update monolog/monolog
composer update monolog/monolog --with-dependencies

İkinci komut, paketin bağımlılıklarının da güncellenmesine izin verir.

Güvenlik ve bakım

composer audit
composer outdated --direct

composer audit, kurulu paketlerde bilinen güvenlik açıklarını listeler. Bunu CI sürecinize eklemek, açık içeren bir paketin fark edilmeden yayına çıkmasını engeller. composer outdated --direct ise yalnızca sizin doğrudan kullandığınız paketlerin güncel olmayanlarını gösterir.

Sık yapılan hatalar

• vendor/ içindeki dosyaları elle düzenlemek. Bir sonraki install ile kaybolur. Paketi değiştirmeniz gerekiyorsa bir yama (patch) aracı kullanın ya da paketi çatallayın (fork).
• Composer'ı root olarak çalıştırmak. Paketlerin içindeki betikler root yetkisiyle çalışır. Proje kullanıcısıyla çalıştırın.
• PHP sürümünü belirtmemek. "php": "^8.2" satırı, Composer'ın sizin PHP sürümünüzle uyumsuz bir paket seçmesini engeller. Canlı sunucunuz daha eski bir PHP kullanıyorsa config.platform.php ayarıyla bunu Composer'a bildirebilirsiniz.

Composer'ı doğru kullanmanın özü iki cümleye sığar: Lock dosyasını commit edin. Canlıda yalnızca install çalıştırın.