İletişim

Composer ile Drupal Kurulumu

Drupal'ı sunucuya indirmenin farklı yolları olsa da güncel projelerde en sağlıklı yöntem Composer kullanmaktır. Composer yalnızca Drupal core dosyalarını indirmez; Drupal'ın ihtiyaç duyduğu PHP paketlerini, modülleri ve diğer bağımlılıkları da yönetir.

Bu sayede projeyi farklı bir sunucuya taşıdığımızda bütün bağımlılıkları tek tek kopyalamak yerine composer.json ve composer.lock dosyaları üzerinden tekrar oluşturabiliriz.

Drupal'ın resmi dokümantasyonunda da yeni projeler için Composer ve drupal/recommended-project yapısı önerilmektedir.

Kuruluma Başlamadan Önce

İlk olarak sunucuda PHP ve Composer'ın kurulu olduğunu kontrol edebiliriz.

PHP sürümünü görmek için:

bash
php -v

Composer için ise:

bash
composer --version

kullanabiliriz.

Örneğin:

text
Composer version 2.8.12

benzeri bir çıktı alıyorsak Composer kullanılabilir durumda demektir.

Drupal 11 için Composer 2.7.0 veya daha yeni bir sürüm gereklidir.

Drupal Projesini Oluşturma

Yeni bir Drupal projesi oluşturmak için:

bash
composer create-project drupal/recommended-project my-drupal-site

komutunu kullanabiliriz.

Buradaki:

text
drupal/recommended-project

Drupal'ın önerdiği proje şablonudur.

text
my-drupal-site

ise oluşturulacak proje dizinidir.

Komut tamamlandığında aşağıdakine benzer bir yapı oluşur:

text
my-drupal-site/
├── composer.json
├── composer.lock
├── vendor/
└── web/

Drupal'ın çalıştırılabilir web dosyaları web dizini içerisinde bulunur. vendor gibi doğrudan ziyaretçilerin erişmesine gerek olmayan dosyalar ise web root dışında kalır. Bu yapı Drupal'ın recommended-project şablonunu önermesinin önemli nedenlerinden biridir.

Web Root Neden web Dizini?

Klasik PHP projelerinde web sunucusunun document root'u doğrudan proje dizini olabilir.

Drupal'ın önerilen Composer yapısında ise web sunucusunun document root'u:

text
/var/www/my-drupal-site/web

olmalıdır.

Yani Nginx veya Apache yapılandırmasını:

text
/var/www/my-drupal-site

yerine:

text
/var/www/my-drupal-site/web

dizinine yönlendiririz.

Böylece:

text
composer.json
composer.lock
vendor/

gibi dosyalar doğrudan web üzerinden erişilebilir olmaz.

Belirli Bir Drupal Sürümünü Kurmak

Her zaman en güncel sürümü kurmak istemeyebiliriz.

Örneğin proje Drupal'ın belirli bir sürümünde başlayacaksa sürümü Composer komutunda belirtebiliriz:

bash
composer create-project drupal/recommended-project:11.2.0 my-drupal-site

Bu durumda Composer belirtilen Drupal sürümünü temel alan projeyi oluşturur.

Belirli bir sürümü sabitlemeden güncel kararlı sürümle başlamak istiyorsak:

bash
composer create-project drupal/recommended-project my-drupal-site

yeterlidir. Drupal'ın resmi kurulum dokümantasyonu da bu komutu temel kurulum yöntemi olarak kullanmaktadır.

composer.json Dosyası Ne İşe Yarar?

Kurulumdan sonra proje kökünde bir composer.json dosyası bulunur.

Bu dosyada projenin hangi paketlere ihtiyaç duyduğu tanımlanır.

Örneğin:

json
{
  "require": {
    "drupal/core-recommended": "^11",
    "drupal/core-composer-scaffold": "^11"
  }
}

Bu örnekte proje Drupal 11 core paketlerine ihtiyaç duyduğunu Composer'a bildirir.

Daha sonra projeye yeni bir Drupal modülü eklediğimizde Composer bu dosyayı otomatik olarak günceller.

composer.lock Neden Önemli?

composer.json hangi paketlerin kullanılabileceğini belirtirken composer.lock kurulumda kullanılan tam paket sürümlerini tutar.

Örneğin iki geliştirici aynı projeyi kendi bilgisayarlarında kurduğunda:

bash
composer install

çalıştırırsa Composer mümkün olduğunca composer.lock içerisinde kayıtlı sürümleri yükler.

Bu nedenle Drupal projelerinde composer.lock dosyasının Git'e eklenmesi gerekir.

Bu dosyanın amacı farklı geliştirme, test ve production ortamlarında aynı bağımlılık sürümlerinin kullanılmasını sağlamaktır.

composer install ve composer update Arasındaki Fark

Composer kullanırken en fazla karıştırılan komutlardan ikisi bunlardır.

bash
composer install

mevcut composer.lock dosyasındaki sürümleri kurar.

Örneğin Git üzerinden projeyi yeni bir sunucuya aldığımızda genellikle:

bash
git clone [email protected]:project/drupal.git
cd drupal
composer install

şeklinde ilerleriz.

composer update ise bağımlılıkların izin verilen yeni sürümlerini araştırabilir ve composer.lock dosyasını değiştirebilir.

Bu nedenle production sunucusunda alışkanlık olarak:

bash
composer update

çalıştırmak doğru değildir.

Güncelleme önce geliştirme ortamında yapılmalı, oluşan composer.lock değişikliği test edilmeli ve daha sonra deployment ile production ortamına aktarılmalıdır.

Drupal Modülü Nasıl Eklenir?

Composer ile yönetilen bir Drupal projesine contributed module eklemek oldukça basittir.

Örneğin Pathauto modülünü eklemek için:

bash
composer require drupal/pathauto

kullanabiliriz.

Composer gerekli paketi indirir ve projenin composer.json ile composer.lock dosyalarını günceller. Drupal'ın resmi Composer dokümantasyonunda da contrib modüllerin bu yöntemle eklenmesi önerilmektedir.

Ancak bu işlem modülü Drupal içerisinde otomatik olarak aktif hale getirmez.

Drush kullanıyorsak ayrıca:

bash
vendor/bin/drush en pathauto

çalıştırabiliriz.

Yani:

bash
composer require

paketi projeye ekler,

bash
drush en

ise Drupal içerisinde modülü etkinleştirir.

Development Paketleri

Bazı paketlere yalnızca geliştirme ortamında ihtiyaç duyarız.

Örneğin Devel modülü:

bash
composer require --dev drupal/devel

şeklinde eklenebilir.

Buradaki:

text
--dev

parametresi paketin production için zorunlu olmadığını belirtir.

Production ortamında:

bash
composer install --no-dev

kullanıldığında development bağımlılıkları kurulmaz.

Drupal'ın resmi dokümantasyonu da production kurulumlarında --no-dev kullanılmasını önerir.

Mevcut Projeyi Yeni Bir Sunucuya Kurmak

Bir Drupal projesini Git'ten yeni bir sunucuya aldığımızı düşünelim.

Örneğin:

bash
git clone [email protected]:project/site.git
cd site

Projenin vendor dizini Git içerisinde bulunmuyorsa bu normaldir.

Gerekli bağımlılıkları yeniden oluşturmak için:

bash
composer install

çalıştırırız.

Production ortamında ise:

bash
composer install --no-dev

kullanılabilir.

Composer bu işlem sırasında composer.lock dosyasını okuyarak projenin ihtiyaç duyduğu paketleri yeniden indirir.

Bu yüzden vendor dizinini Git repository içerisinde tutmak çoğu Composer tabanlı projede gerekli değildir.

vendor Dizini Neden Önemli?

Drupal'ın çalışması için yalnızca web/core dizininin bulunması yeterli değildir.

Symfony bileşenleri ve diğer PHP bağımlılıkları vendor içerisinde bulunur.

Örneğin Git üzerinden Drupal kodlarını aldıktan sonra Composer çalıştırılmazsa:

text
vendor/autoload.php not found

benzeri bir hata görülebilir.

Bu durumda genellikle çözüm:

bash
composer install

çalıştırmaktır. Drupal'ın resmi dokümantasyonu da Git ile alınan kod tabanlarında bağımlılıkların Composer ile kurulması gerektiğini özellikle belirtiyor.

Composer ile Drupal Core Güncelleme

Composer'ın önemli avantajlarından biri güncelleme işlemlerinin kontrollü yapılabilmesidir.

Yalnızca Drupal core paketlerini güncellemek istediğimizde örneğin:

bash
composer update drupal/core-recommended \
  drupal/core-composer-scaffold \
  drupal/core-project-message \
  --with-all-dependencies

kullanılabilir.

Güncellemeden sonra Drupal veritabanı güncellemelerini de çalıştırmak gerekir.

Drush kullanıyorsak:

bash
vendor/bin/drush updatedb

ardından cache temizlemek için:

bash
vendor/bin/drush cr

çalıştırabiliriz.

Composer paket dosyalarını günceller; updatedb ise Drupal modüllerinin ihtiyaç duyduğu veritabanı güncellemelerini çalıştırır. Bunlar birbirinden farklı işlemlerdir.

Composer'da Sık Karşılaşılan Hatalar

Kurulum sırasında karşılaşılan hataların önemli bir bölümü PHP sürümü veya eksik PHP extension'larından kaynaklanır.

Örneğin:

text
requires php >=8.x

hatası görüyorsak sunucudaki PHP sürümü yüklemeye çalıştığımız paketin gereksinimini karşılamıyor olabilir.

Benzer şekilde:

text
ext-gd is missing

veya:

text
ext-xml is missing

hataları ilgili PHP extension'ının sistemde bulunmadığını gösterir.

Bu nedenle yalnızca:

bash
php -v

kontrolü yapmak her zaman yeterli değildir.

Aktif PHP extension'larını görmek için:

bash
php -m

kullanabiliriz.

Bir başka önemli nokta, web sunucusunun kullandığı PHP ile terminaldeki PHP sürümünün farklı olabilmesidir. Özellikle birden fazla PHP sürümü bulunan sunucularda Composer CLI üzerindeki PHP sürümünü kullanır.

Composer'ı Root Olarak Çalıştırmalı mıyız?

Sunucu üzerinde:

bash
sudo composer install

kullanmak ilk bakışta izin sorunlarını çözmüş gibi görünebilir ancak proje dosyalarının sahibinin root olmasına neden olabilir.

Daha sonra web sunucusu veya deployment kullanıcısı bu dosyalara erişmeye çalışırken yeni izin problemleri ortaya çıkabilir.

Bu nedenle Composer komutlarını mümkün olduğunca projenin sahibi olan normal kullanıcıyla çalıştırmak daha sağlıklıdır.

Örneğin:

bash
cd /var/www/my-drupal-site
composer install

şeklinde çalıştırmadan önce dizinin owner ve permission yapısının doğru olduğundan emin olunmalıdır.

Özet Bir Kurulum

Sıfırdan basit bir Drupal projesi başlatıyorsak temel süreç şu kadar kısa olabilir:

bash
composer create-project drupal/recommended-project my-drupal-site

cd my-drupal-site

composer require drush/drush

Ardından web sunucusunun document root'unu:

text
my-drupal-site/web

olarak ayarlayıp daha önce hazırladığımız veritabanı bilgileriyle Drupal kurulum ekranına geçebiliriz.

Sonuç

Composer, güncel Drupal projelerinde yalnızca bir paket indirme aracı değildir. Core, contributed module ve PHP bağımlılıklarının hangi sürümlerde kullanılacağını merkezi olarak yönetmemizi sağlar.

Yeni bir Drupal projesi oluştururken:

bash
composer create-project drupal/recommended-project my-drupal-site

ile başlamak, Drupal'ın önerilen proje yapısını kullanmamızı sağlar.

Sonraki süreçte de modül ekleme, core güncelleme ve deployment işlemlerinin Composer üzerinden yönetilmesi; geliştirme, test ve production ortamlarının mümkün olduğunca aynı bağımlılıklarla çalışmasını kolaylaştırır.

Son güncelleme: 18.09.2026 13:52