PHP Composer Kullanımı: Bağımlılık Yönetimi Rehberi

PHP Composer, modern PHP geliştirmenin omurgasıdır: projenizin ihtiyaç duyduğu kütüphaneleri indiren, sürümlerini yöneten ve sınıfları otomatik yükleyen bağımlılık (dependency) yöneticisidir. NPM'in JavaScript için yaptığını Composer PHP için yapar. Bu yazıda Composer'ı sıfırdan kurmaktan, require ile paket eklemeye, composer.lock dosyasının mantığından PSR-4 autoload'a kadar günlük kullanımda ihtiyaç duyacağınız her şeyi gerçek, çalışan örneklerle ele alıyoruz.

Composer nedir ve neden gerekli?

Eskiden PHP'de bir kütüphane kullanmak için dosyaları manuel indirip require ile tek tek dahil etmek gerekirdi. Bu yöntem hem hataya açıktı hem de sürüm güncellemeyi kâbusa çeviriyordu. Composer üç temel sorunu çözer:

Bağımlılık çözümü: Bir paketin ihtiyaç duyduğu başka paketleri (ve onların da bağımlılıklarını) otomatik bulur ve uyumlu sürümleri kurar.
Sürüm yönetimi: Hangi sürümün kabul edilebilir olduğunu tanımlarsınız, Composer bu kurala uyan en uygun sürümü seçer.
Autoload: Sınıflarınızı ve paketleri elle require etmeden, isimlerine göre otomatik yükler.

Paketler Packagist (packagist.org) adlı merkezi depodan çekilir. Laravel, Symfony, Guzzle, PHPUnit gibi ekosistemin tamamı buradan dağıtılır. Her paketin benzersiz bir satıcı/paket (vendor/package) adı vardır; örneğin guzzlehttp/guzzle. Bu isimlendirme, farklı geliştiricilerin aynı isimde paket yayınlayıp çakışmasını önler ve hangi paketi kurduğunuzu net biçimde belirtir.

Kurulum ve ilk proje

Composer'ı işletim sisteminize göre kurabilirsiniz; Linux/macOS'ta resmi kurulum betiği, Windows'ta ise hazır yükleyici vardır. Kurulumu doğrulamak için:

composer --version

Yeni bir projeye başlarken interaktif bir sihirbaz çalıştırabilir ya da doğrudan composer.json üretebilirsiniz:

composer init

Bu komut size paket adı, açıklama, lisans ve ilk bağımlılıkları sorar ve kök dizinde bir composer.json dosyası oluşturur. Bu dosya projenizin kimlik kartıdır; bağımlılıklar, autoload kuralları ve metaveri burada tutulur.

Paket kurmak: require ve install

Bir paket eklemenin en doğrudan yolu require komutudur. Örneğin popüler HTTP istemcisi Guzzle'ı kurmak için:

composer require guzzlehttp/guzzle

Bu komut paketi indirir, composer.json dosyasına ekler, composer.lock dosyasını günceller ve vendor/ klasörüne yerleştirir. Belirli bir sürüm kısıtı da verebilirsiniz:

composer require guzzlehttp/guzzle:^7.5

Yalnızca geliştirme ortamında gereken araçları (test kütüphaneleri, kod analizcileri) --dev ile ekleyin; bunlar üretim kurulumuna dahil edilmez:

composer require --dev phpunit/phpunit

Bir projeyi klonladığınızda bağımlılıkları kurmak için ise install kullanırsınız. Bu komut composer.lock dosyasındaki tam sürümleri okuyup birebir kurar:

composer install

Üretim sunucusunda geliştirme bağımlılıklarını atlamak ve autoload'u optimize etmek için sık kullanılan kombinasyon şudur:

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

composer.json ve composer.lock farkı

Bu iki dosyanın rolünü karıştırmak en yaygın kafa karışıklığıdır. composer.json sizin niyetinizi tanımlar: "Guzzle'ın 7.x sürümlerinden herhangi biri olur." composer.lock ise o anki gerçeği kaydeder: "Guzzle tam olarak 7.8.1 kuruldu." Tipik bir require bölümü şöyle görünür:

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

Sürüm operatörlerinin anlamı kritik:

^7.5 — 7.5 ve üzeri, ama 8.0'dan küçük. En sık kullanılan, "uyumlu güncellemelere izin ver" operatörüdür.
~7.5 — 7.5 ve üzeri, ama 7.6'dan küçük (yalnızca yama sürümleri).
7.5.* — 7.5 serisindeki herhangi bir yama.

Altın kural: composer.lock dosyasını mutlaka versiyon kontrolüne (Git) ekleyin. Böylece ekipteki herkes ve üretim sunucusu aynı sürümleri kurar; "bende çalışıyordu" sorunlarının önüne geçersiniz.

update ve install ne zaman?

İkisi arasındaki ayrım bağımlılık yönetiminin kalbidir. composer install kilit dosyasına sadık kalır ve hiçbir sürümü değiştirmez. composer update ise composer.json'daki kısıtlar dahilinde paketleri en güncel uyumlu sürümlere yükseltir ve composer.lock'u yeniden yazar:

composer update

Yalnızca tek bir paketi güncellemek isterseniz adını verin:

composer update monolog/monolog

Üretim sunucusunda asla composer update çalıştırmayın. Bu komut sürümleri değiştireceği için canlı ortamda beklenmedik kırılmalara yol açabilir. Güncellemeyi yerel ortamda yapın, test edin, yeni composer.lock'u commit'leyin; sunucuda yalnızca composer install çalışsın.

Autoload: PSR-4 ile kendi sınıflarınız

Composer'ın en güçlü özelliği autoload'dur. Kendi sınıflarınızı da Composer'a yükletmek için composer.json'a bir PSR-4 eşlemesi ekleyin. Bu, bir namespace ön ekini bir klasöre bağlar:

{
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

Bu eşleme şu anlama gelir: App\Services\Mailer sınıfı src/Services/Mailer.php dosyasında aranır. Eşlemeyi ekledikten sonra autoload haritasını yeniden üretmeniz gerekir:

composer dump-autoload

Artık projenizin giriş noktasında tek bir satır yeterlidir. Composer'ın ürettiği autoloader'ı dahil edince hem kendi sınıflarınız hem de tüm paketler otomatik yüklenir:

require __DIR__ . '/vendor/autoload.php';

use App\Services\Mailer;

$mailer = new Mailer();

Üretimde performans için --optimize-autoloader (kısaca -o) bayrağı, sınıf-dosya eşlemesini önceden hesaplayarak çalışma anındaki dosya aramalarını ortadan kaldırır.

Composer scripts ile otomasyon

composer.json içindeki scripts bölümü, sık kullandığınız komutlara kısayol tanımlamanızı sağlar:

{
    "scripts": {
        "test": "phpunit",
        "check": [
            "@php -l src/",
            "phpunit"
        ]
    }
}

Bunları composer test veya composer check ile çalıştırırsınız. Ayrıca post-install-cmd gibi olay kancaları, kurulumdan sonra otomatik görevler tetiklemek için kullanılır — Laravel'in kurulum sonrası anahtar üretmesi buna örnektir. Scriptler, ekipteki herkesin aynı komutları aynı şekilde çalıştırmasını sağlayarak proje bakımını standartlaştırır; yeni katılan bir geliştirici uzun komutları ezberlemek yerine yalnızca composer kısayollarını öğrenir.

Sık Sorulan Sorular

composer.lock dosyasını Git'e eklemeli miyim?

Evet, kesinlikle. Uygulama projelerinde composer.lock her zaman commit edilmelidir; bu, tüm geliştiricilerin ve üretim sunucusunun birebir aynı sürümleri kurmasını garanti eder. Yalnızca başkalarının kullanacağı bir kütüphane (paket) geliştiriyorsanız, composer.lock'u depoya eklememek yaygın bir tercihtir.

"Class not found" hatası alıyorum, neden?

En sık neden, autoload haritasının güncel olmamasıdır. Yeni bir PSR-4 namespace eklediyseniz ya da dosya/klasör adlarını değiştirdiyseniz composer dump-autoload komutunu çalıştırın. Ayrıca namespace'in dosya yolu ve sınıf adıyla büyük/küçük harf dahil tam eşleştiğinden emin olun.

require ile require-dev arasındaki fark nedir?

require, uygulamanın çalışması için her ortamda gereken paketleri tutar. require-dev ise yalnızca geliştirme sırasında gereken araçları (PHPUnit, statik analiz, hata ayıklayıcılar) tutar. Üretimde composer install --no-dev ile bu geliştirme bağımlılıkları kurulmaz, böylece kurulum daha hafif ve güvenli olur.

PHP projenizde bağımlılık yönetimi mi karmaşıklaştı? Composer kurulumu, autoload yapılandırması, sürüm çakışmaları ya da Laravel/Symfony tabanlı bir projenin temiz mimarisi için yardıma ihtiyacınız olursa benimle iletişime geçin — projenizi birlikte sağlam bir temele oturtalım.