Paylaşımlı Hostingde Composer Nasıl Çalıştırılır?

Elinizde çalışan bir Laravel, Symfony veya basit bir PHP projesi var. Yerel makinenizde composer install çalıştırdınız, vendor klasörü oluştu, her şey yolunda. Sonra projeyi paylaşımlı hostinge FTP ile yüklediniz ve tarayıcıda açtığınızda karşınıza şu çıktı: Fatal error: Uncaught Error: Class "App\Http\Kernel" not found veya require(): Failed opening required '/home/kullanici/vendor/autoload.php'. Dosyalar orada duruyor, klasör listesinde vendor görünüyor, ama uygulama onları göremiyor.

Bu tablonun sebebi neredeyse hiçbir zaman "eksik dosya" değildir. Composer'ın ürettiği vendor klasörü, taşınabilir bir dosya yığını değil, kurulduğu makineye göre üretilmiş bir haritadır. O haritanın içinde mutlak dosya yolları, PHP sürüm kontrolleri ve bazen platforma özel derlenmiş bileşenler bulunur. FTP ile aktardığınızda dosyalar taşınır ama harita geride kalır.

Bu yazıda önce bu bozulmanın tam olarak nasıl gerçekleştiğini göstereceğim; sonra iki farklı senaryo için doğru yöntemi anlatacağım: sunucunuzda SSH erişimi varsa composer.phar dosyasını ev dizininize kurup doğru PHP ikilisiyle çalıştırma, SSH yoksa yerelde --no-dev ile üretim kurulumu yapıp taşımanın kurallı hâli. Arada da paylaşımlı hostingde herkesin başına gelen bellek limiti hatasını çözeceğiz.

"vendor Klasörünü FTP ile At" Tavsiyesi Neden Çoğu Zaman Bozuk Kurulum Üretir?#

İnternetteki forum cevaplarının büyük kısmı "SSH yoksa vendor'ı yerelde oluştur, FTP ile yükle, biter" der. Bu cümle teknik olarak yanlış değil, ama eksik olduğu için pratikte bozuk kurulum üretir. Beş ayrı sebep var ve hepsi ayrı bir hata mesajıyla karşınıza çıkar.

1. autoload_static.php mutlak yollar tutar#

composer install çalıştığında vendor/composer/ altında autoload_static.php, autoload_psr4.php ve installed.php gibi dosyalar üretilir. Bunlarda projenin kök dizini gömülüdür. Yerel makinenizde bu yol C:\projeler\site veya /Users/emre/projeler/site iken, sunucuda /home/kullanici/uygulama olur. Composer bazı yolları göreli tutsa da, özellikle installed.php içindeki install_path değerleri ve bazı paketlerin kendi ürettiği önbellek dosyaları mutlak kalır. Sonuç: sınıf var, dosya var, ama autoloader onu bulamıyor.

2. platform-check.php sürüm uyuşmazlığını sertçe keser#

Composer 2, kurulum sırasında hedef PHP sürümüne göre vendor/composer/platform_check.php üretir. Yerelinizde PHP 8.3 varsa ve sunucuda 8.1 çalışıyorsa, bu dosya uygulamayı daha ilk satırda durdurur:

Fatal error: Composer detected issues in your platform:
Your Composer dependencies require a PHP version ">= 8.3.0".

Dosya siliniyor diye bir çözüm önerenler olur — silmeyin. O kontrol, gerçekten uyumsuz bir kodun sunucuda garip yerlerde patlamasını engelliyor.

3. Geliştirme bağımlılıkları da taşınır#

Yerelde composer install varsayılan olarak require-dev altındaki paketleri de kurar. PHPUnit, Faker, debug bar, statik analiz araçları... Bunlar üretim sunucusunda hem gereksiz yer kaplar hem de bazıları hata ayıklama uçları açarak güvenlik riski oluşturur. Boyut farkı da ciddidir: geliştirme paketleriyle 90 MB olan bir vendor klasörü, --no-dev ile 25 MB'a inebilir.

4. Dosya sayısı FTP'yi ve inode kotanızı vurur#

Orta ölçekli bir Laravel projesinin vendor klasöründe 15.000-30.000 dosya bulunur. FTP bunları tek tek aktarır; her dosya için ayrı bir bağlantı turu gerekir. Yükleme saatler sürer, arada kopan bağlantı yüzünden sessizce eksik kalan dosyalar olur ve bu eksikler ancak o kod yolu çalıştığında ortaya çıkar. Ayrıca paylaşımlı paketlerin çoğunda dosya sayısı (inode) kotası vardır; ayrıntısı disk kotası ve inode yazısında.

5. Sembolik bağlar ve çalıştırma izinleri kaybolur#

vendor/bin/ altındaki komutlar çoğu sistemde sembolik bağdır. FTP bunları ya düz dosya olarak kopyalar ya da hiç taşımaz; çalıştırma izinleri de yolda kaybolur. php vendor/bin/phpunit gibi çağrılar "command not found" verir.

Bunların hepsinin ortak paydası şu: vendor klasörünü taşımak yanlış değil, kontrolsüz taşımak yanlış. Aşağıda ikisinin de doğrusunu göreceğiz.

Önce Karar: Sunucunuzda SSH Erişimi Var mı?#

Yönteminizi belirleyen tek soru budur. Kontrol etmek için cPanel ana ekranında Terminal simgesini arayın ya da SSH Access bölümüne bakın. Simge görünmüyorsa paket bunu kapatmış olabilir; bazı sağlayıcılar talep üzerine açar.

SSH varsa kesinlikle o yolu seçin: bağımlılıklar sunucunun kendi PHP sürümüne, kendi eklenti listesine göre çözülür ve yukarıdaki beş sorunun beşi de ortadan kalkar. Terminal erişimini açma adımları cPanel SSH erişimi ve Terminal yazısında anlatılıyor.

SSH Varsa: composer.phar'ı Ev Dizinine Kurmak#

Paylaşımlı hostingde sudo yetkiniz yoktur, bu yüzden Composer'ı sistem geneline kuramazsınız. Kurmanız da gerekmez — Composer tek bir PHP dosyasıdır (composer.phar) ve ev dizininizden gayet iyi çalışır.

Adım 1 — Kişisel bir bin klasörü açın:

mkdir -p ~/bin

Adım 2 — Kurulum betiğini indirip çalıştırın:

cd ~
curl -sS https://getcomposer.org/installer -o composer-setup.php
php composer-setup.php --install-dir=$HOME/bin --filename=composer
rm composer-setup.php

curl çalışmıyorsa PHP'nin kendisiyle de indirebilirsiniz:

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"

Adım 3 — ~/bin klasörünü PATH'e ekleyin ki her seferinde tam yol yazmayın:

echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
composer --version

Çıktı Composer version 2.x.x şeklindeyse kurulum tamamdır. Sonradan güncellemek için composer self-update yeterlidir; ana sürüm atlamak istemiyorsanız composer self-update --2 ile 2.x serisinde kalabilirsiniz.

Doğru php-cli Binary'sini Seçmek#

Bu adım atlandığında saatler kaybedilir. Paylaşımlı sunucuda php komutunun işaret ettiği sürüm, sitenizin web tarafında çalışan sürümle aynı olmak zorunda değildir. cPanel'in MultiPHP Manager'ından siteyi PHP 8.2'ye almış olabilirsiniz ama komut satırındaki varsayılan hâlâ 7.4 olabilir. Composer da bağımlılıkları gördüğü sürüme göre çözer; sonuçta üretim sitesinde çalışmayan bir vendor klasörü elde edersiniz.

Önce durumu tespit edin:

which php
php -v
php -r 'echo PHP_BINARY, PHP_EOL;'

Sunucuda kurulu diğer sürümleri listeleyin:

ls -1 /opt/cpanel/ | grep ea-php
# ea-php74  ea-php80  ea-php81  ea-php82  ea-php83

Sonra Composer'ı istediğiniz sürümle açıkça çağırın. Sarmalayıcıya güvenmek yerine ikiliyi doğrudan yazmak en güvenli yoldur:

/opt/cpanel/ea-php82/root/usr/bin/php ~/bin/composer install --no-dev --optimize-autoloader

Bunu her seferinde yazmamak için .bashrc dosyanıza bir takma ad tanımlayın:

echo "alias php82='/opt/cpanel/ea-php82/root/usr/bin/php'" >> ~/.bashrc
echo "alias composer82='/opt/cpanel/ea-php82/root/usr/bin/php $HOME/bin/composer'" >> ~/.bashrc
source ~/.bashrc

CloudLinux kullanan sunucularda yollar /opt/alt/php82/usr/bin/php biçimindedir. Sürümler arası geçişin cPanel tarafındaki karşılığı için PHP sürüm yönetimi yazısına bakabilirsiniz.

Kurulumdan önce projenin gereksinimlerinin sunucuda karşılandığını doğrulayın; bu komut eksik eklentileri tek tek listeler:

composer check-platform-reqs

Çıktıda ext-intl missing gibi bir satır görürseniz kuruluma başlamadan önce cPanel'in PHP eklenti seçicisinden o modülü açmanız gerekir.

Composer Memory Limit Hatasını Aşmak#

Paylaşımlı hostingde en sık karşılaşılan Composer hatası budur:

PHP Fatal error: Allowed memory size of 134217728 bytes exhausted
(tried to allocate 20480 bytes) in phar:///home/kullanici/bin/composer/...

Sebep, bağımlılık çözümleme (dependency resolution) adımının doğası gereği bellek yemesidir. Composer, uyumlu sürüm kombinasyonlarını bulmak için bütün olasılık ağacını bellekte tutar. Orta ölçekli bir projede bu 500 MB'ı, karmaşık projelerde 1 GB'ı aşabilir.

Üç kademeli çözüm uygulayın:

Kademe 1 — Composer'ın kendi bellek değişkeni:

COMPOSER_MEMORY_LIMIT=-1 composer install --no-dev --optimize-autoloader

Kademe 2 — PHP'ye doğrudan bayrak geçirmek. Sunucunun php.ini dosyasını değiştiremiyorsanız çalıştırma anında geçersiz kılabilirsiniz:

php -d memory_limit=-1 ~/bin/composer install --no-dev --optimize-autoloader

Kademe 3 — İşi hafifletmek. Bellek limiti sert bir tavansa (bazı sağlayıcılar -1 değerini yok sayar), Composer'a daha az iş verin:

# Yerelde çözülmüş kilit dosyasını kullan, ağacı yeniden hesaplama
composer install --no-dev --prefer-dist --no-scripts

Buradaki püf nokta composer.lock dosyasıdır. composer install kilit dosyası varsa sürüm ağacını yeniden hesaplamaz, sadece kilitteki tam sürümleri indirir — bellek tüketimi kat kat düşer. composer update ise ağacı sıfırdan çözer ve asıl belleği o yer. Kural basittir: composer update komutunu yerel makinenizde çalıştırın, sunucuda sadece composer install kullanın ve composer.lock dosyasını mutlaka depoya dahil edin.

Aynı hatanın web tarafındaki hâli ve memory_limit ayarının ayrıntıları için Allowed memory size exhausted hatası yazısına göz atın.

"Killed" Mesajı Bellek Hatası Değildir#

Bazen ekranda hata yerine sadece Killed yazar ve komut biter. Bu, PHP'nin bellek limiti değil, sunucunun işlem denetleyicisinin (LVE / cgroup) sizi durdurduğu anlamına gelir. Fiziksel bellek veya CPU kotanız dolmuştur. Çözüm:

# İndirme ve çıkarma işini paralel yapma, tek tek yürüt
composer install --no-dev --prefer-dist -vvv

# Composer önbelleğini temizleyip yeniden dene
composer clear-cache

Yine olmuyorsa iş yükünü sunucudan çıkarın: kurulumu yerelde yapıp taşıyın (bir sonraki bölüm) ya da hesabınızın kaynak limitlerini yükseltmeyi değerlendirin.

SSH Yoksa: Yerelde Kurup Doğru Şekilde Taşımak#

SSH erişiminiz hiç yoksa vendor klasörünü taşımak zorundasınız — ama baştaki beş sorunu tek tek kapatarak.

Adım 1 — Hedef PHP sürümünü composer.json içinde sabitleyin. Sunucudaki sürümü cPanel'in MultiPHP ekranından veya bir phpinfo() dosyasından öğrenin, sonra yerelde şunu çalıştırın:

composer config platform.php 8.1.29

Bu satır composer.json dosyasına bir config.platform bloğu ekler. Artık yerelinizde PHP 8.3 olsa bile Composer, sunucuda 8.1 varmış gibi davranır ve o sürümle uyumlu paket sürümlerini seçer. platform-check hatası da böylece ortadan kalkar.

Adım 2 — Üretim kurulumunu yapın:

rm -rf vendor
composer install --no-dev --optimize-autoloader --classmap-authoritative

Bayrakların anlamı:

⚠️ --classmap-authoritative bayrağını yalnızca sınıflarınızı dinamik olarak üretmiyorsanız kullanın; bazı eklenti sistemleri bu modda çalışmaz.

Adım 3 — Tek dosya hâlinde sıkıştırın. 20.000 dosyayı FTP ile teker teker göndermeyin:

zip -r vendor.zip vendor

Adım 4 — Zip'i yükleyip sunucuda çıkarın. cPanel Dosya Yöneticisi'nde yükleme yapıp dosyaya sağ tıklayıp Extract deyin. Bu adım hem dakikalar yerine saniyeler sürer hem de yarım kalan aktarım riskini ortadan kaldırır. Aktarım yöntemleri arasındaki farklar için FTP/SFTP ile dosya yükleme yazısı yardımcı olur.

Adım 5 — Autoloader'ı sunucu yoluna göre yenileyin. Bu adım genellikle atlanır ve asıl "class not found" hatasının kaynağı budur. SSH yoksa, public_html dışına küçük bir PHP dosyası koyup tarayıcıdan bir kez çalıştırarak sınıf haritasını yeniden ürettirebilirsiniz — ancak Composer'ın kendisi sunucuda yoksa bu mümkün olmaz. Bu durumda çareler şunlardır: sağlayıcıdan tek seferlik SSH açmasını istemek, ya da composer.json içindeki autoload.psr-4 yollarını göreli tutup --optimize-autoloader yerine standart autoloader ile kurulum yapmak. Optimize edilmemiş autoloader biraz daha yavaştır ama mutlak yol gömmez, dolayısıyla taşınabilirdir.

Adım 6 — Doğrulayın. Uygulamanın ana sayfasını açmadan önce basit bir test dosyasıyla autoloader'ı sınayın:

<?php
require __DIR__ . '/vendor/autoload.php';
echo 'Autoloader yuklendi', PHP_EOL;
var_dump(class_exists(\Monolog\Logger::class));

Kurulumu Kilitleyen İki Sessiz Engel: allow-plugins ve post-install Betikleri#

Composer 2.2 ile birlikte eklentiler için açık izin zorunlu hâle geldi. Bir paket kendini "Composer eklentisi" olarak tanımlıyorsa (kurulum yolunu değiştiren composer/installers, otomatik betik çalıştıran php-http/discovery gibi) Composer size onay sorar. Etkileşimli terminalde bu bir soru kutusudur; cron veya betik içinde çalıştırdığınızda ise hiçbir uyarı vermeden eklentiyi atlar ve paket beklediği yere kurulmaz.

İzni kalıcı olarak vermek için:

composer config --no-plugins allow-plugins.composer/installers true
composer config --no-plugins allow-plugins.php-http/discovery true

Bu komutlar composer.json içine bir config.allow-plugins bloğu yazar; dosyayı depoya eklerseniz sunucuda tekrar sormaz. Hepsine birden izin veren allow-plugins: true biçimini kullanmayın — üçüncü parti bir paketin kurulum sırasında kod çalıştırmasına koşulsuz izin vermiş olursunuz.

İkinci engel post-install-cmd betikleridir. Laravel'de bu adım package:discover çalıştırır, bazı projelerde ise varlık derleme, önbellek ısıtma veya veritabanı taşıma komutları tetikler. Paylaşımlı hostingde bunlar işlem limitine takılıp kurulumu yarıda kesebilir. Kurulumu betiksiz yapıp betikleri sonra elle çalıştırmak daha kontrollüdür:

composer install --no-dev --optimize-autoloader --no-scripts
composer run-script post-install-cmd

Betik adımı hata verirse en azından paketleriniz eksiksiz kurulmuş olur ve sorunu ayrı ayrı çözebilirsiniz.

Kurulum Sonrası Kontrol Listesi#

Kurulum bittiğinde şu komutlarla durumu teyit edin. Hepsi Composer 2 ile birlikte gelir:

# composer.json sözdizimi ve alan doğruluğu
composer validate --strict

# Ortam sorunlarını (bellek, ağ, izin, disk) tarar
composer diagnose

# Kurulu paket ve sürümlerini listeler
composer show --installed

# Bilinen güvenlik açığı olan paketleri raporlar
composer audit

Bir de şu üç dosya/klasör kontrolünü yapın:

1. vendor/autoload.php mevcut ve okunabilir mi?
2. vendor/composer/installed.php içindeki yollar sunucudaki gerçek yola mı işaret ediyor?
3. .env, composer.json ve composer.lock dosyaları web'den erişilebilir bir klasörde mi kaldı? Kaldıysa public_html dışına taşıyın veya .htaccess ile erişimi kapatın.

Son olarak sürüm kontrolü kullanıyorsanız iş akışı çok daha temiz olur: vendor klasörünü depoya hiç koymayın, composer.lock dosyasını koyun, sunucuda git pull sonrası composer install --no-dev çalıştırın. cPanel'in kendi Git arayüzü bu akışı destekler; ayrıntısı cPanel Git sürüm kontrolü yazısında.

Sıkça Sorulan Sorular#

Paylaşımlı hostingde Composer kurulabilir mi?#

Evet. Composer sistem geneline kurulmak zorunda değildir; tek bir PHP arşiv dosyasıdır ve ev dizininizde çalışır. SSH veya cPanel Terminal erişiminiz varsa kurulum betiğini indirip ~/bin klasörüne yerleştirmeniz yeterlidir, root yetkisi gerekmez. Erişim yoksa Composer'ı sunucuda çalıştıramazsınız ve bağımlılıkları yerel makinenizde çözüp taşımanız gerekir.

vendor klasörünü FTP ile yüklemek neden hata veriyor?#

Üç ana sebep var: autoloader dosyaları kurulduğu makinenin dosya yollarını içerir, platform_check.php yerel PHP sürümünü sunucudakiyle karşılaştırıp uygulamayı durdurur ve on binlerce dosyanın FTP aktarımı sırasında bir kısmı sessizce eksik kalır. Doğru yöntem, kurulumu sunucunun PHP sürümüne sabitleyerek yapmak, klasörü zip'leyip tek dosya olarak yüklemek ve sunucuda çıkarmaktır.

composer install ile composer update arasındaki fark nedir?#

composer install, composer.lock dosyasındaki tam sürümleri indirir; sürüm ağacını yeniden hesaplamadığı için hızlı ve bellek dostudur. composer update ise composer.json içindeki aralıklara bakıp en uygun sürümleri baştan çözer, kilit dosyasını günceller ve asıl belleği tüketen adım budur. Üretim sunucusunda daima install kullanın, update komutunu yerel makinenizde çalıştırın.

Composer memory limit hatasını nasıl çözerim?#

Önce COMPOSER_MEMORY_LIMIT=-1 composer install deneyin. İşe yaramazsa PHP'ye doğrudan bayrak geçirin: php -d memory_limit=-1 ~/bin/composer install. Sağlayıcı sınırsız değeri kabul etmiyorsa iş yükünü azaltın; composer.lock dosyasının depoda olduğundan emin olup yalnızca install çalıştırın ve --no-dev --prefer-dist bayraklarını ekleyin. Bu üç adım vakaların büyük kısmını çözer.

Komut satırındaki PHP sürümü siteminkinden farklı olabilir mi?#

Evet ve bu çok yaygın bir tuzaktır. cPanel'in MultiPHP Manager'ından değiştirdiğiniz sürüm web isteklerini etkiler; komut satırındaki varsayılan php ise başka bir sürümü işaret edebilir. Composer bağımlılıkları gördüğü sürüme göre çözdüğü için sonuçta sitede çalışmayan bir kurulum elde edersiniz. php -v ile kontrol edin ve gerekiyorsa /opt/cpanel/ea-php82/root/usr/bin/php gibi tam yolu açıkça yazın.

composer.lock dosyasını depoya eklemeli miyim?#

Kesinlikle evet. Kilit dosyası, projenin her ortamda birebir aynı paket sürümleriyle kurulmasını sağlar; onsuz geliştirici makinesi ile sunucuda farklı sürümler oluşur ve "bende çalışıyordu" sorunları başlar. Ayrıca sunucuda composer install komutunun bağımlılık ağacını yeniden hesaplamasını engelleyerek bellek tüketimini ciddi biçimde düşürür. Depoya eklemeyeceğiniz tek şey vendor klasörüdür.