Composer Hatası Nasıl Çözülür? Problem 1 ve Paket Gereksinimleri

Composer hata çözümü, Composer’ın composer.json içindeki sürüm kısıtları ile PHP ve eklenti gibi platform gereksinimlerini aynı anda karşılayan bir bağımlılık kümesi bulamamasıyla başlar. Çözüm için son genel hata satırına takılmak yerine Problem 1 ve devamındaki requires, conflicts, PHP ve ext-* satırlarını okuyarak çakışmanın türünü belirlemelisin.

Composer’ın yazdığı Your requirements could not be resolved to an installable set of packages ifadesi sonucu özetler, tek başına kök nedeni açıklamaz. Önce Problem 1 altındaki paket adı, istenen sürüm, mevcut PHP sürümü veya eksik eklenti bilgisini incele; birden fazla problem varsa diğerlerini de aynı sınıflandırmayla değerlendir.

Hata mesajı ne anlama gelir ve neden önce Problem 1 okunmalıdır?

Composer bağımlılıkları tek tek değil, birlikte çalışabilecek bir küme olarak çözer. Örneğin bir paket belirli bir PHP sürümü isterken başka bir paket farklı bir sürüm aralığı isteyebilir. Benzer biçimde, doğrudan eklediğin bir paket geçişli olarak başka bir paket sürümünü talep edebilir veya sistemindeki PHP eklentilerinden birinin bulunmasını bekleyebilir.

Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - Root composer.json requires ...
    - some/package requires ...
    - another/package conflicts with ...

Bu yapıda ilk satır genel sonucu, Problem 1 bölümü ise çözümleyicinin hangi koşulları aynı anda karşılayamadığını gösterir. Root composer.json requires satırı projedeki doğrudan isteği, requires satırı bir paketin başka bir paket veya platform koşuluna bağımlılığını, conflicts satırı ise iki koşulun birlikte kullanılamadığını anlatır. Bazı çıktılarda bir paket sürümü bulunmasına rağmen başka bir gereksinimle çakıştığı için çözüm kümesine alınmadığı da belirtilir.

Problem 1 satırını paket, PHP, eklenti ve geçişli bağımlılık olarak sınıflandırma

Problem 1 satırlarını aşağıdaki karar ağacıyla okuyabilirsin. Her dalda önce hata satırındaki belirleyici ifadeyi bul, ardından ilgili dosya veya çalışma ortamını kontrol et.

1. Belirli paket sürümleri çakışıyorsa: Root composer.json requires vendor/package ... veya found ... but these were not loaded, likely because it conflicts with another require satırını oku. Önce kök composer.json içindeki doğrudan bağımlılıkları ve bunların sürüm aralıklarını kontrol et. Güvenli ilk adım, birbiriyle uyumlu sürüm aralıklarını belirlemek ve yalnızca ilgili bağımlılıkları değiştirmektir. Rastgele paket silmek veya tüm bağımlılıkları körlemesine yükseltmek çözüm değildir.
2. PHP sürümü uyuşmuyorsa: requires php ... but your php version ... does not satisfy that requirement ifadesini ara. Hata satırındaki gerekli sürüm ile terminalde Composer’ı çalıştıran PHP sürümünü karşılaştır; ayrıca composer.json içindeki require.php ve varsa platform ayarlarını incele. İlk adım, uyumlu bir PHP çalışma ortamı kullanmak veya mevcut PHP sürümünü destekleyen bir paket sürümü seçmektir. Platform koşulunu yok saymak, paketin çalışma zamanındaki uyumsuzluğunu ortadan kaldırmaz.
3. PHP eklentisi eksik veya etkin değilse: requires ext-... ve özellikle it is missing from your system satırlarını kontrol et. Yerel PHP’nin etkin modüllerini, CLI ortamının kullandığı php.ini dosyasını ve Composer’ın gördüğü platform paketlerini incele. Bunun için şu komutlar başlangıç kontrolü sağlar:

php --version
php -m
composer show --platform
composer validate

php --version Composer’ın hangi PHP yorumlayıcısıyla çalıştığını, php -m etkin modülleri, composer show --platform ise Composer’ın gördüğü PHP ve ext-* koşullarını gösterir. Eksik eklenti için güvenli ilk adım, eklentiyi doğru CLI PHP ortamında etkinleştirmek veya kurmaktır. Composer platform paketlerini kendisi yüklenebilir normal paketler gibi çözmez.

1. Geçişli bağımlılık çakışıyorsa: Satır doğrudan Root composer.json ile değil, başka bir paketle başlıyorsa çatışma geçişli olabilir. Örneğin birinci paket ikinci paketin belirli sürümlerini isterken, senin doğrudan bağımlılığın aynı paketin farklı bir aralığını isteyebilir. Önce composer.json içindeki doğrudan paketi, sonra composer.lock içindeki çözülmüş bağımlılıkları kontrol et. İlk adım, zincirdeki hangi doğrudan gereksinimin değiştirilebileceğini belirlemektir.
2. Lock dosyası ile proje koşulları uyuşmuyorsa: is locked to version ... and an update of this package was not requested benzeri satırlar, composer.lock içindeki çözümün mevcut composer.json veya PHP platformuyla birlikte kullanılamadığını gösterebilir. İki dosyanın uyumunu ve gerçek PHP ortamını kontrol et. Lock dosyasını silmek yerine, mevcut kilitli çözümü koruyarak kuruluma devam edip etmeyeceğine veya ilgili bağımlılığı bilinçli biçimde güncelleyip güncellemeyeceğine karar ver.

composer.json, composer.lock, require, install ve update farkı

Bu beş öğe aynı işi yapmaz. composer.json projenin hangi koşulları istediğini tanımlar, composer.lock ise çözülmüş paket sürümlerini sabitler. Komut seçimi, yeni paket eklemek mi, mevcut çözümü kurmak mı, yoksa bağımlılıkları yeniden çözmek mi istediğine göre yapılmalıdır.

Doğrudan bağımlılıklar genellikle composer.json içinde açıkça yer alır. Bu paketlerin ihtiyaç duyduğu geçişli bağımlılıklar ise çözüm sonucuyla birlikte composer.lock dosyasına yazılır. Lock dosyası mevcut olduğunda composer install, depolarda bulunan daha yeni sürümleri kendiliğinden seçmek yerine kilitlenmiş sürümleri kullanır. composer update ise composer.json koşullarına göre çözümlemeyi yeniler. Uygulama projelerinde lock dosyasını sürüm kontrolünde tutmak, farklı ortamlarda aynı çözümün kurulmasına yardımcı olur.

Bağımlılık yönetimi ve hata ayıklama mantığını farklı örneklerle pekiştirmek için teknik yazılar arşivindeki ilgili içeriklere göz atabilirsin.

Güvenli teşhis için composer why-not, diagnose ve dry-run nasıl kullanılır?

Bu komutlar farklı soruları yanıtlar: why-not bir paket sürümünün veya PHP hedefinin neden engellendiğini, diagnose Composer ortamında yaygın bir sorun olup olmadığını, --dry-run ise bir güncellemenin hangi işlemleri planladığını gösterir. Composer belgelerinde why-not, prohibits komutunun eş anlamlısı olarak kullanılır. Composer komut satırı belgeleri bu komutların kullanımını açıklar.

why-not ile engelleyici bağımlılığı bul

composer why-not vendor/package hedef-sürüm
composer why-not php hedef-sürüm

İlk komut, belirtilen paket sürümünün projedeki gereksinimlerle neden uyuşmadığını araştırır. Çıktıda başka bir paketin istediği sürüm aralığı veya PHP gibi bir platform koşulu engel olabilir. İkinci komut, mevcut bağımlılıkların belirtilen PHP hedefiyle nerede çakıştığını gösterir. Örneğin bir satırda paketin php (<8.2) istediğini görürsen, bu gereksinim hedef PHP sürümüyle uyuşmayabilir. Çıktıda paket adıyla birlikte görünen requires veya conflicts bilgisi, incelenecek bağımlılık ilişkisini işaret eder.

diagnose ve dry-run ile ortamı ve planı incele

composer diagnose
composer update vendor/package --dry-run

composer diagnose, Composer yapılandırması ve ortamla ilgili yaygın sorunları otomatik kontrollerle tarar. Sonuçlarda uyarı veya hata olarak belirtilen satırları, bağlantı ve yapılandırma gibi ortam sorunları açısından incele. Bu komut bağımlılık çakışmasını tek başına çözmez; yalnızca teşhise yardımcı olur. composer update vendor/package --dry-run ise hedef paketin güncelleme çözümünü ve planlanan işlemleri gösterir, işlemleri uygulamaz. Plan çıktısında eklenecek, güncellenecek veya kaldırılacak paketleri kontrol et. Çözümleme başarısızsa Problem 1 altındaki gereksinim satırları hangi koşulun karşılanmadığını belirtir.

--ignore-platform-reqs, PHP ve ext-* gibi platform gereksinimi kontrollerini atlayabilir. Bu nedenle gerçek PHP veya eklenti uyumsuzluğunu gizleme riski taşır; teşhisin varsayılan adımı olarak kullanma.

Küçük örnek: paket sürümü ile PHP gereksinimi çakışmasını dry-run ile inceleme

Aşağıdaki örnekte yerel komut satırı PHP sürümünün 8.3.0 olduğunu varsayalım. symfony/var-dumper paketinin v8.1.7 sürüm bilgisi PHP için >=8.4.1 gereksinimini belirtir. Bu iki koşul uyuşmadığından, proje tam olarak bu sürümü istediğinde Composer çözümleme hatası verir.

{
  "require": {
    "symfony/var-dumper": "8.1.7"
  }
}

Önce Composer'ın çalıştığı PHP sürümünü kontrol et:

php -v

Örneğin çıktının başında PHP 8.3.0 (cli) yazıyorsa, paket gereksinimi bu yerel PHP sürümünde karşılanmıyor. Ardından çözümü dosyalara uygulamadan dene:

composer update symfony/var-dumper --dry-run

Hata çıktısında belirleyici bölümün anlamı şöyledir:

symfony/var-dumper v8.1.7 requires php >=8.4.1
your php version (8.3.0) does not satisfy that requirement

Bu satırlar paketin istediği alt PHP sınırını ve yerel sürümün neden yetersiz kaldığını gösterir. Composer çıktısının çevresindeki satırlar projeye ve çözümleme durumuna göre değişebilir. Engeli ayrıca sorgulamak için:

composer why-not symfony/var-dumper 8.1.7

Çıktıda PHP gereksinimini belirten paket satırını ara. Buradaki sorun paketin adında veya JSON sözdiziminde değil, seçilen paket sürümünün PHP koşulundadır.

Kök nedene göre güvenli çözüm sırası

1. PHP ve eklentileri doğrula. php -v ile Composer'ın kullandığı PHP sürümünü, php -m ile etkin eklentileri kontrol et. Hata ext-... koşulundan söz ediyorsa, ilgili eklentinin aynı PHP ortamında etkin olup olmadığını araştır.
2. Doğrudan gereksinimleri ve kilitli çözümü karşılaştır. composer.json projenin istediği sürüm aralıklarını, composer.lock ise çözümlenmiş paket sürümlerini gösterir. Hata belirli bir kilitli pakete işaret ediyorsa, bütün bağımlılıkları değiştirmek yerine ilgili sürüm ilişkisini incele.
3. Doğrudan bağımlılık çakışıyorsa uyumlu aralığı değerlendir. Paket sürüm aralığını ancak proje kodunun ve kullandığın PHP ortamının desteklediği seçenekler arasından belirle. Sonucu hedefli bir güncellemenin --dry-run çıktısıyla kontrol et.
4. Engel geçişli bağımlılıktaysa zinciri bul. composer why-not vendor/package hedef-sürüm ile hangi paketin sürüm koşulunu daralttığını gör. Ardından yalnızca ilgili paketi ve gerekiyorsa ilişkili bağımlılıkları hedefleyen bir güncellemenin planını incele.
5. Değişikliği gözden geçirip uygun komutu seç. Kilit dosyasıyla eşleşen mevcut çözümü kurmak gerekiyorsa composer install, bağımlılık çözümünü değiştirmek gerekiyorsa uygun kapsamda composer update kullanılır. Güncellemeden önce dry-run çıktısındaki ekleme, yükseltme ve kaldırmaları kontrol et.

Paketleri gelişigüzel silmek, tüm bağımlılıkları gerekçesiz yükseltmek veya composer.lock dosyasını refleks olarak kaldırmak, hangi koşulun çakıştığını açıklamaz. Önce Problem 1 altındaki gereksinimi belirle, sonra değişikliği bu kök nedene göre sınırla.

Son kontrol listesi: hata çıktısından uygulanabilir eyleme

Composer hatasında işe son satırdaki genel mesajla değil, Problem 1 ve altındaki gereksinimlerle başla. Aşağıdaki sıra, hangi kısıtın değişmesi gerektiğini belirlemene ve çözümün beklenmedik paket güncellemelerine yol açıp açmayacağını görmene yardımcı olur.

1. Engeli oku: Problem 1 altında hangi paketin hangi sürümü istediğini ve Composer’ın neden o sürümü seçemediğini belirle. Genel hata satırı bu ayrıntıyı vermez.
2. Sorunu sınıflandır: Engellenen şey bir paket sürümü mü, php gereksinimi mi, ext-* eklentisi mi? Bir paket başka bir paketi gerektiriyorsa geçişli bağımlılık zincirini de izle.
3. Dosyaları karşılaştır: composer.json içindeki kısıtlarla composer.lock dosyasında sabitlenen sürümleri karşılaştır. Özellikle install sırasında, değiştirdiğin gereksinimin kilitli sürümlerle uyumlu olup olmadığına bak.
4. Teşhisi daralt: composer why-not komutuna engellenen paket veya php ile sınamak istediğin sürümü ver; hangi bağımlılığın buna karşı çıktığını incele. composer diagnose ise yaygın yapılandırma sorunlarını kontrol eder, fakat tek başına paket çakışmasının nedenini açıklamak zorunda değildir.
5. Değişikliği önce dene: Yapacağın işleme uygun --dry-run seçeneğiyle planlanan kurulum veya güncellemeyi incele. Çakışma sürüyorsa yeni Problem 1 satırlarını oku; çözülüyorsa hangi paketlerin değişeceğini kontrol et.
6. Sonucu doğrula: Gerekli düzeltmeden sonra işlemi yeniden çalıştır. composer.lock değiştiyse farkı incele; amaçladığın düzeltmeyle ilgisiz sürüm değişikliklerini gözden geçir.

Paket kısıtları çakışıyorsa uygun kısıtı yeniden değerlendirmek, platform gereksinimi uyuşmuyorsa PHP’yi veya ilgili eklentiyi uyumlu hâle getirmek gerekebilir. Geçişli bağımlılık engelinde ise bütün projeyi güncellemek yerine etkilenen bağımlılık zincirini hedeflemek daha kontrollü bir seçenek olabilir. Bağımlılık ve sürüm kısıtı kavramlarını ayrıca gözden geçirmek için yazılım bilgi testlerine bakabilirsin.

Sık Sorulan Sorular

Problem 1 satırı neden son satırdaki genel Composer hata mesajından daha önemlidir?

Son satır bağımlılıkların çözümlenemediğini bildirir. Problem 1 ve devamındaki satırlar ise hangi gereksinimin hangi paket veya platform koşuluyla çatıştığını gösterir. Düzeltilecek kısıtı bu ayrıntılardan çıkarırsın.

composer install ile composer update arasındaki fark nedir?

composer.lock varsa composer install dosyada sabitlenen paket sürümlerini kullanır. composer update ise composer.json içindeki kısıtlara göre bağımlılıkları yeniden çözümler ve sonuçta composer.lock dosyasını güncelleyebilir.

composer why-not komutu hangi soruyu yanıtlar?

Belirttiğin paket veya PHP sürümünün projede kullanılmasını hangi bağımlılıkların engellediğini gösterir. Komuta hedefi ve sınamak istediğin sürümü birlikte vermen gerekir.

--ignore-platform-reqs kullanmak güvenli bir çözüm müdür?

Tek başına çözüm değildir. Bu seçenek PHP ve eklenti gibi platform gereksinimlerini göz ardı eder; paketlerin çalışacağı ortamı uyumlu hâle getirmez. Önce hangi gereksinimin karşılanmadığını belirle.

composer.lock dosyasını silmek bu hatayı çözer mi?

Dosyayı silmek, kilitli sürümleri korumadan bağımlılıkların yeniden çözümlenmesine yol açabilir; asıl çakışmayı düzeltmeyebilir. Önce composer.json, kilitli sürümler ve hata satırları arasındaki uyuşmazlığı incele.

Kısacası, genel hata mesajını değil gereksinim zincirini izle; düzeltmeyi uygulamadan önce etkisini denetle.