Composer Nedir? PHP Projelerinde Bağımlılık Yönetimi ve Sunucu Kullanımı

Son Güncelleme: Ağustos 2026

Composer, PHP projelerinde kullanılan kütüphaneleri yönetmek, sürüm uyumluluğunu korumak ve uygulama dağıtımlarını daha düzenli hale getirmek için kullanılan bir bağımlılık yönetim aracıdır. Özellikle Laravel, Symfony, CodeIgniter, özel PHP yazılımları ve kurumsal web uygulamalarında Composer kullanımı, sunucu tarafında güvenli ve tekrarlanabilir kurulum süreçleri oluşturmanın temel adımlarından biridir.

Bu rehberde Composer’ın ne işe yaradığını, composer.json ve composer.lock dosyalarının görevlerini, Linux sunucuda Composer kullanımında dikkat edilmesi gereken noktaları, performans ve güvenlik önerilerini ayrıntılı şekilde ele alacağız.

İçindekiler

• Composer Nedir?
• Composer Nasıl Çalışır?
• composer.json ve composer.lock Dosyaları
• Sunucuda Composer Kullanımı
• En Sık Kullanılan Composer Komutları
• Performans ve Güvenlik Önerileri
• Yaygın Composer Hataları ve Çözümleri
• Pratik Kullanım Senaryoları
• Sıkça Sorulan Sorular
• Sonuç

Composer Nedir?

Composer, PHP ekosisteminde paketleri, kütüphaneleri ve bu paketlerin ihtiyaç duyduğu alt bağımlılıkları yöneten bir araçtır. Bir PHP projesinde e-posta gönderimi, ödeme sistemi entegrasyonu, loglama, HTTP istemcisi, şablon motoru veya framework bileşeni kullanmak istediğinizde bu bileşenleri tek tek indirip klasörlere kopyalamak yerine Composer ile yönetebilirsiniz.

Composer, projenizin ihtiyaç duyduğu paketleri tanımlamanıza, uygun sürümleri indirmenize ve otomatik yükleme sistemi olan autoload mekanizmasını oluşturmanıza yardımcı olur. Bu sayede geliştirici, test ve canlı sunucu ortamlarında aynı paket sürümleriyle çalışmak mümkün hale gelir.

Composer’ı yalnızca bir paket indirme aracı olarak düşünmek eksik olur. Composer aynı zamanda sürüm kontrolü, bağımlılık çözümleme, otomatik sınıf yükleme ve dağıtım standardizasyonu sağlayan kritik bir geliştirme aracıdır.

Composer Hangi Sorunları Çözer?

• Manuel kütüphane yönetimini azaltır: Paketleri tek tek indirip güncelleme ihtiyacını ortadan kaldırır.
• Sürüm uyumluluğu sağlar: Hangi paketin hangi sürümünün kullanılacağını net biçimde tanımlar.
• Ortam tutarlılığı sunar: Geliştirme, test ve canlı ortamda aynı bağımlılıkların kurulmasına yardımcı olur.
• Autoload üretir: Sınıfların otomatik yüklenmesini sağlayarak require karmaşasını azaltır.
• Framework kurulumlarını kolaylaştırır: Laravel gibi modern PHP frameworklerinin çalışması için temel bir rol oynar.

Composer Nasıl Çalışır?

Composer, proje kök dizininde bulunan composer.json dosyasını okuyarak ihtiyaç duyulan paketleri belirler. Ardından bu paketlerin sürüm kurallarını analiz eder, gerekli alt bağımlılıkları çözer ve paketleri genellikle vendor dizinine indirir. Kurulum tamamlandığında vendor/autoload.php dosyası oluşturulur.

PHP uygulamanızda Composer tarafından indirilen paketleri kullanmak için çoğu zaman aşağıdaki satırı eklemeniz yeterlidir:

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

Bu autoload dosyası, projenizde kullanılan sınıfların otomatik olarak yüklenmesini sağlar. Özellikle PSR-4 autoloading standardı sayesinde modern PHP uygulamalarında klasör yapısı daha düzenli hale gelir.

Bağımlılık Çözümleme Mantığı

Bir paket başka paketlere ihtiyaç duyabilir. Örneğin projenize bir HTTP istemci paketi eklediğinizde bu paket, kendi içinde farklı arayüz paketlerine veya yardımcı bileşenlere ihtiyaç duyabilir. Composer bu zinciri analiz ederek gerekli tüm paketleri uygun sürümleriyle birlikte kurar.

Bu süreçte sürüm kısıtları önemlidir. Örneğin ^2.0 ifadesi, genellikle ana sürüm 2 içinde uyumlu güncellemeleri kabul eder. ~1.5 gibi ifadeler ise daha dar bir sürüm aralığı belirleyebilir. Yanlış sürüm kısıtları, canlı ortamda beklenmeyen uyumsuzluklara yol açabileceği için dikkatli kullanılmalıdır.

composer.json ve composer.lock Dosyaları

Composer kullanılan her projede iki dosya özellikle önemlidir: composer.json ve composer.lock. Bu dosyalar benzer görünse de görevleri farklıdır.

composer.json Örneği

Basit bir PHP projesinde composer.json dosyası aşağıdaki gibi olabilir:

{
  "require": {
    "php": "^8.2",
    "monolog/monolog": "^3.0"
  },
  "autoload": {
    "psr-4": {
      "App\\": "src/"
    }
  }
}

Bu örnekte proje, PHP 8.2 ve üzeri uyumlu bir ortam ile monolog/monolog paketinin 3.x uyumlu sürümlerini talep eder. autoload bölümünde ise App\ isim alanının src/ dizinine karşılık geldiği belirtilir.

composer.lock Neden Silinmemelidir?

composer.lock dosyası, uygulamanın hangi paket sürümleriyle test edildiğini gösterir. Canlı sunucuda composer install komutu çalıştırıldığında Composer bu dosyaya bakarak birebir aynı paket sürümlerini kurar. Eğer bu dosya silinir ve composer update çalıştırılırsa paketler daha yeni sürümlere geçebilir. Bu durum bazı projelerde uyumluluk sorunlarına, hata mesajlarına veya beklenmeyen davranışlara neden olabilir.

Sunucuda Composer Kullanımı

Composer hem geliştirme bilgisayarında hem de sunucu ortamında kullanılabilir. Ancak canlı sunucuda Composer kullanırken güvenlik, performans ve yetki yönetimi konularına dikkat edilmelidir. Özellikle paylaşımlı hosting, VPS, VDS veya kiralık sunucu ortamlarında Composer komutlarının hangi kullanıcıyla çalıştırıldığı önemlidir.

Composer Kurulum Kontrolü

Sunucuda Composer kurulu olup olmadığını kontrol etmek için aşağıdaki komut kullanılabilir:

composer --version

Eğer Composer sistem genelinde kurulu değilse, kullanıcı bazlı veya proje bazlı kurulum tercih edilebilir. Paylaşımlı ortamlarda sistem geneline kurulum için yetki bulunmayabilir; bu durumda hosting panelinizin terminal özelliği veya SSH erişimi üzerinden kullanıcı seviyesinde kullanım yapılabilir.

Canlı Ortamda Doğru Komut Kullanımı

Canlı ortamda çoğu durumda composer update yerine composer install kullanılmalıdır. Çünkü install, composer.lock dosyasındaki kesin sürümleri kurar. update ise paket sürümlerini değiştirebilir.

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

Bu komutta kullanılan parametrelerin anlamı şöyledir:

• --no-dev: Test, debug ve geliştirme araçları gibi canlı ortamda gerekmeyen paketleri kurmaz.
• --optimize-autoloader: Autoload haritasını optimize ederek sınıf yükleme performansını artırır.

Root Kullanıcı ile Çalıştırma Konusu

Composer komutlarının gereksiz yere root kullanıcı ile çalıştırılması önerilmez. Çünkü paket scriptleri çalışabilir ve yanlış yapılandırılmış bir paket veya script, sistem dosyalarına erişim riski oluşturabilir. En güvenli yaklaşım, uygulamaya ait özel bir Linux kullanıcısı oluşturmak ve Composer işlemlerini bu kullanıcı ile yürütmektir.

Uygulama ve Composer işlemleriniz için izole, kaynakları size ayrılmış bir ortam gerekiyorsa Sanal Sunucu veya yüksek performanslı projeler için Kiralık Sunucu altyapısı tercih edilebilir.

En Sık Kullanılan Composer Komutları

Composer ile etkili çalışmak için temel komutları bilmek gerekir. Aşağıdaki komutlar PHP projelerinde en sık kullanılan işlemleri kapsar.

Paket Kurma

Yeni bir paket eklemek için require komutu kullanılır:

composer require vendor/paket-adi

Örneğin loglama için Monolog paketi eklemek isterseniz:

composer require monolog/monolog

Bağımlılıkları Kurma

Mevcut bir projeyi sunucuya taşıdığınızda paketleri kurmak için:

composer install

Canlı ortam için daha uygun kullanım:

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

Paketleri Güncelleme

Tüm paketleri sürüm kurallarına göre güncellemek için:

composer update

Yalnızca belirli bir paketi güncellemek daha kontrollü bir yaklaşımdır:

composer update vendor/paket-adi

Autoload Yenileme

Yeni sınıf, klasör veya autoload ayarı eklediğinizde aşağıdaki komut kullanılabilir:

composer dump-autoload

Canlı ortamda optimize edilmiş autoload üretmek için:

composer dump-autoload -o

Güvenlik Denetimi

Projede bilinen güvenlik açığı bulunan paketleri kontrol etmek için:

composer audit

Bu komut, bağımlılıklarınızda bilinen güvenlik sorunları olup olmadığını kontrol etmenize yardımcı olur. Özellikle e-ticaret, üyelik sistemi, ödeme entegrasyonu veya kullanıcı verisi işleyen projelerde düzenli çalıştırılması önemlidir.

Performans ve Güvenlik Önerileri

Composer kullanımı doğru yapılandırıldığında projenizi düzenli hale getirir; yanlış kullanıldığında ise canlı ortamda performans, güvenlik ve dağıtım sorunlarına neden olabilir. Aşağıdaki öneriler özellikle VPS, VDS, bulut sunucu ve kiralık sunucu ortamlarında önemlidir.

Canlı Ortamda Geliştirme Paketlerini Kurmayın

require-dev altında bulunan paketler genellikle test, debug, kod kalite kontrolü veya geliştirme amaçlıdır. Canlı ortamda bu paketlere ihtiyaç yoktur. Bu nedenle üretim ortamında her zaman şu komut tercih edilmelidir:

composer install --no-dev

Autoload Optimizasyonu Yapın

Büyük projelerde yüzlerce sınıf ve paket bulunabilir. Optimize edilmemiş autoload yapısı, istek başına fazladan dosya kontrolüne neden olabilir. Bu nedenle dağıtım sırasında şu komut kullanılmalıdır:

composer install --no-dev --classmap-authoritative

--classmap-authoritative parametresi, Composer’ın sınıf haritasını daha katı şekilde kullanmasını sağlar. Ancak dinamik sınıf yükleme yapan bazı projelerde dikkatli test edilmelidir.

vendor Dizinini Web Kökünün Dışında Tutun

Mümkünse vendor dizini doğrudan web üzerinden erişilebilir olmamalıdır. Uygulamanın yalnızca public dizini dış dünyaya açılmalı, diğer uygulama dosyaları web kökünün dışında kalmalıdır. Bu yaklaşım Laravel gibi modern frameworklerde standart güvenlik mimarisidir.

Dosya Sahipliği ve İzinleri Kontrol Edin

Composer komutları yanlış kullanıcı ile çalıştırıldığında vendor, storage veya cache dizinlerinde sahiplik sorunları oluşabilir. Örneğin web sunucusu kullanıcısı dosyalara erişemediğinde 500 hataları görülebilir. Dosya sahipliği uygulama kullanıcısı ve web sunucusu yapılandırmasına göre düzenlenmelidir.

chown -R uygulama:uygulama /var/www/proje

Bu komut örnektir; gerçek kullanıcı ve dizin adları sunucu yapınıza göre değiştirilmelidir.

Kaynak Kullanımını Planlayın

Composer bazı büyük projelerde yüksek bellek kullanabilir. Özellikle düşük RAM’e sahip sunucularda paket çözümleme sırasında bellek hataları görülebilir. Bu nedenle yoğun PHP projeleri için yeterli RAM, hızlı disk ve güncel PHP sürümü önemlidir. Kaynak ihtiyacı yüksek projelerde Türkiye VDS Sunucu veya Bulut Sunucu seçenekleri daha esnek bir çalışma ortamı sağlayabilir.

Yaygın Composer Hataları ve Çözümleri

Composer kullanırken karşılaşılan hatalar genellikle PHP sürümü, eksik eklentiler, bellek limiti, dosya izinleri veya paket sürüm uyumsuzluklarından kaynaklanır. Aşağıda sık karşılaşılan problemler ve çözüm yaklaşımları yer alır.

PHP Sürümü Uyumsuzluğu

Bir paket, sunucuda kurulu PHP sürümünden daha yeni bir sürüm isteyebilir. Hata mesajında genellikle paketin hangi PHP sürümünü istediği açıkça belirtilir. Çözüm olarak PHP sürümünü yükseltmek veya paket sürüm kısıtını projenizle uyumlu hale getirmek gerekir.

php -v

Panel tabanlı hosting kullanıyorsanız PHP sürümünü kontrol panelinden değiştirebilirsiniz. Kendi sunucunuzu yönetiyorsanız PHP-FPM, web sunucusu ve CLI PHP sürümlerinin aynı olup olmadığını da kontrol etmelisiniz.

Eksik PHP Extension Hataları

Bazı paketler extension yani PHP eklentilerine ihtiyaç duyar. Örneğin ext-curl, ext-mbstring, ext-zip, ext-intl gibi eklentiler sık kullanılır. Eksik eklentiyi görmek için:

php -m

Eksik modül kurulduktan sonra web sunucusu veya PHP-FPM servisi yeniden başlatılmalıdır. Aksi halde CLI tarafında çalışan eklenti web tarafında aktif olmayabilir.

Memory Limit Hatası

Büyük bağımlılık ağaçlarında Composer bellek limiti hatası verebilir. Geçici çözüm olarak aşağıdaki komut kullanılabilir:

COMPOSER_MEMORY_LIMIT=-1 composer install

Bu komut bellek limitini kaldırır; ancak kalıcı çözüm sunucunun kaynaklarını doğru planlamak ve gereksiz paketleri projeden temizlemektir.

Dosya İzni Hataları

vendor dizinine yazılamıyor, cache dizini oluşturulamıyor veya lock dosyası güncellenemiyor gibi hatalar dosya izinlerinden kaynaklanabilir. Komutu çalıştıran kullanıcının proje dizinine yazma yetkisi olduğundan emin olunmalıdır.

ls -la /var/www/proje

Platform Requirement Hataları

Bazen paketler belirli PHP sürümü veya eklenti gereksinimleri nedeniyle kurulmaz. Geliştirme aşamasında geçici test için --ignore-platform-reqs kullanılabilir; ancak bu parametre canlı ortamda dikkatli kullanılmalıdır. Gereksinimleri görmezden gelmek, uygulamanın çalışma anında hata vermesine neden olabilir.

composer install --ignore-platform-reqs

Pratik Kullanım Senaryoları

Composer, yalnızca framework projelerinde değil, özel PHP uygulamalarında da düzenli bir yapı kurmak için kullanılabilir. Aşağıdaki senaryolar, sunucu ve hosting ortamlarında Composer’ın nasıl konumlandırılabileceğini gösterir.

Senaryo 1: Laravel Projesini Canlı Sunucuya Alma

Laravel projelerinde Composer temel gereksinimlerden biridir. Proje dosyaları sunucuya aktarıldıktan sonra genellikle şu adımlar uygulanır:

composer install --no-dev --optimize-autoloader
php artisan config:cache
php artisan route:cache
php artisan view:cache

Bu işlem bağımlılıkları kurar ve Laravel yapılandırma önbelleklerini hazırlar. Ancak her dağıtım öncesinde veritabanı yedeği almak, bakım modu kullanmak ve hata durumunda geri dönüş planı hazırlamak önemlidir.

Senaryo 2: Özel PHP Projesinde Autoload Kullanımı

Framework kullanmayan bir PHP projesinde de Composer ile düzenli klasör yapısı oluşturabilirsiniz. Örneğin src/ dizininde sınıflarınızı tutup PSR-4 autoload kullanabilirsiniz.

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

Ardından autoload dosyasını yenileyebilirsiniz:

composer dump-autoload

Senaryo 3: CI/CD Sürecinde Composer

Modern dağıtım süreçlerinde Composer komutları otomatik pipeline içinde çalıştırılabilir. Bu yaklaşım, insan hatasını azaltır ve her dağıtımda aynı adımların uygulanmasını sağlar.

composer install --no-dev --prefer-dist --optimize-autoloader
composer audit

--prefer-dist parametresi paketlerin dağıtım arşivleri üzerinden kurulmasını tercih eder ve çoğu durumda daha hızlı kurulum sağlar.

Senaryo 4: Paylaşımlı Hosting Ortamında Composer

Paylaşımlı hosting paketlerinde SSH erişimi varsa Composer komutları kullanıcı seviyesinde çalıştırılabilir. SSH erişimi yoksa bağımlılıklar yerel geliştirme ortamında kurulup vendor diziniyle birlikte yüklenebilir. Küçük ve orta ölçekli PHP projeleri için Linux Hosting pratik bir seçenek olabilir. Daha fazla kontrol, özel PHP sürümü veya arka plan işlemi gerekiyorsa VPS/VDS tarafına geçmek daha doğru olur.

Sıkça Sorulan Sorular

Sonuç

Composer, modern PHP projelerinde bağımlılık yönetimi, autoload düzeni, sürüm tutarlılığı ve güvenli dağıtım süreçleri için vazgeçilmez bir araçtır. Doğru kullanıldığında PHP uygulamalarının geliştirme, test ve canlı ortamlar arasında daha kararlı çalışmasını sağlar. Özellikle composer.lock dosyasının korunması, canlı ortamda composer install --no-dev --optimize-autoloader kullanılması ve gereksiz root yetkilerinden kaçınılması, sağlıklı bir sunucu yönetimi için kritik öneme sahiptir.

Küçük PHP projeleri için Hosting çözümleri yeterli olabilirken, Laravel veya yüksek trafikli özel uygulamalar için Sanal Sunucu, Bulut Sunucu veya Kiralık Sunucu altyapıları daha fazla kontrol ve performans sunar. Corelux altyapı çözümleriyle Composer tabanlı PHP projelerinizi güvenli, performanslı ve ölçeklenebilir şekilde barındırabilirsiniz.