Drupal Ayar Dosyalarının Yapılandırılması

Drupal kurulumunu tamamladıktan sonra proje bazında en sık düzenlediğimiz dosyalardan biri settings.php olur. Veritabanı bağlantısı, güvenilir domainler, configuration dizini ve ortama özel bazı ayarlar bu dosya üzerinden yönetilebilir.

Standart bir Composer kurulumunda dosyayı genellikle şu konumda görürüz:

web/sites/default/settings.php

Drupal ayrıca lokal geliştirme veya test ortamlarında ana ayarları değiştirmeden farklı değerler kullanabilmek için settings.local.php yapısını da destekler.

settings.php Dosyası Ne İşe Yarar?

settings.php, Drupal'ın siteye özel ayarlarını tuttuğu dosyadır.

Örneğin burada:

• veritabanı bağlantısı,
• trusted host ayarları,
• configuration sync dizini,
• hash salt,
• dosya sistemiyle ilgili bazı ayarlar,
• reverse proxy ayarları

gibi değerler bulunabilir.

Drupal kurulumu sırasında bu dosyanın önemli bir bölümü otomatik olarak hazırlanır.

settings.php Nasıl Oluşur?

Drupal içerisinde örnek ayar dosyası şu konumda bulunur:

web/sites/default/default.settings.php

Kurulum yapılırken bundan bir settings.php oluşturulur.

Manuel hazırlamak gerekirse:

cp web/sites/default/default.settings.php \
   web/sites/default/settings.php

komutu kullanılabilir.

Ancak Drupal Installer ile normal kurulum yapıldığında çoğu zaman bu işlemi bizim yapmamız gerekmez.

Veritabanı Ayarları

Önceki yazıda oluşturduğumuz veritabanı bilgileri Drupal tarafından settings.php içerisine kaydedilir.

Örneğin:

$databases['default']['default'] = [
  'database' => 'drupal_site',
  'username' => 'drupal_user',
  'password' => 'GucluBirSifreBuraya',
  'host' => 'localhost',
  'port' => '3306',
  'driver' => 'mysql',
  'prefix' => '',
  'collation' => 'utf8mb4_general_ci',
];

Buradaki değerleri tek tek ele alırsak:

database, Drupal'ın kullanacağı veritabanının adıdır.

username ve password, bu veritabanına bağlanacak kullanıcı bilgileridir.

host, veritabanı sunucusunun adresini belirtir.

driver ise Drupal'ın hangi veritabanı sürücüsünü kullanacağını belirler. MySQL ve MariaDB için bu değer genellikle mysql olur. Drupal'ın güncel default.settings.php dosyasında da temel bağlantı yapısı bu şekilde tanımlanmaktadır.

localhost Her Zaman Doğru mu?

Hayır.

Drupal ile MySQL aynı sunucuda klasik bir kurulumla çalışıyorsa:

'host' => 'localhost',

doğru olabilir.

Ancak Docker gibi container tabanlı ortamlarda veritabanı başka bir container içerisinde çalışabilir.

Örneğin Docker Compose içerisinde veritabanı servisimiz:

services:
  db:
    image: mariadb

ise Drupal tarafındaki host değeri çoğunlukla:

'host' => 'db',

olur.

Çünkü container içerisinde localhost, o an çalışan Drupal container'ını ifade eder.

Veritabanı Bilgilerini Git'e Eklemeli miyiz?

Bu konu proje yapısına göre değişebilir ancak production veritabanı şifresini doğrudan Git repository içerisinde tutmak iyi bir yaklaşım değildir.

Örneğin bilgiler environment variable üzerinden alınabilir:

$databases['default']['default'] = [
  'database' => getenv('DB_NAME'),
  'username' => getenv('DB_USER'),
  'password' => getenv('DB_PASSWORD'),
  'host' => getenv('DB_HOST') ?: 'localhost',
  'driver' => 'mysql',
];

Böylece farklı ortamlarda aynı kod kullanılabilirken veritabanı bilgileri sunucu tarafında ayrı tutulabilir.

Drupal'ın güvenlik dokümantasyonu da hassas bilgilerin document root dışında veya uygun bir secret yönetimi yöntemiyle saklanabileceğini belirtmektedir.

Trusted Host Ayarı

Production ortamında düzenlenmesi gereken önemli ayarlardan biri trusted_host_patterns değeridir.

Örneğin sitemiz:

example.com

ve:

www.example.com

adreslerinden çalışacaksa:

$settings['trusted_host_patterns'] = [
  '^example\.com$',
  '^www\.example\.com$',
];

şeklinde tanımlayabiliriz.

Bu değerler normal domain değil, regular expression olarak yazılır.

Bu nedenle:

.

karakterleri:

\.

şeklinde escape edilir.

Trusted Host ayarı, HTTP Host Header üzerinden yapılabilecek bazı saldırılara karşı koruma sağlar. Tanımlanan pattern ile eşleşmeyen bir host üzerinden istek gelirse Drupal HTTP 400 yanıtı verir.

Alt Domainler Kullanılıyorsa

Örneğin şu adreslerin tamamı projeye ait olabilir:

example.com
www.example.com
test.example.com
stage.example.com

Hepsini ayrı ayrı yazmak yerine uygun bir regex kullanılabilir.

Örneğin:

$settings['trusted_host_patterns'] = [
  '^(.*\.)?example\.com$',
];

Bu yapı example.com ile birlikte alt domainlerin de eşleşmesini sağlar.

Ancak trusted host pattern'ını gereğinden fazla geniş tutmamak gerekir. Amaç hangi domainlerden erişime izin verildiğini açık şekilde sınırlandırmaktır.

Configuration Sync Dizini

Drupal Configuration Management kullanıyorsak configuration dosyalarının export edildiği dizini de settings.php içerisinde belirleyebiliriz.

Örneğin:

$settings['config_sync_directory'] = '../config/sync';

Bu durumda proje yapımız şöyle olabilir:

project/
├── config/
│   └── sync/
├── vendor/
└── web/

Burada config dizini web root'un dışında kalır.

Configuration export işlemi yaptığımızda:

vendor/bin/drush cex

YAML dosyaları bu dizine yazılır.

Import sırasında:

vendor/bin/drush cim

aynı dizindeki configuration dosyaları kullanılır.

Drupal 8.8 ve sonrasında sync dizini $settings['config_sync_directory'] üzerinden tanımlanmaktadır.

hash_salt Nedir?

settings.php içerisinde karşılaşacağımız bir diğer değer:

$settings['hash_salt'] = '...';

ayarının kendisidir.

Drupal bunu tek kullanımlık giriş bağlantıları, form token'ları ve benzeri güvenlikle ilişkili işlemlerde kullanır.

Normal kurulum sırasında Drupal bu değeri otomatik oluşturur.

Bu nedenle var olan bir siteyi başka bir sunucuya taşırken settings.php dosyasını yeniden oluşturuyorsak eski hash_salt değerini yanlışlıkla kaybetmemek gerekir.

Değer değişirse bazı mevcut tek kullanımlık bağlantılar geçersiz hale gelebilir. Drupal dokümantasyonunda aynı site birden fazla web sunucusunda çalışıyorsa hash_salt değerinin bütün sunucularda aynı olması gerektiği de belirtilmektedir.

settings.local.php Neden Kullanılır?

Development ortamında production'dan farklı ayarlara ihtiyaç duymamız normaldir.

Örneğin lokal ortamda:

• cache kapatmak,
• CSS/JS aggregation kapatmak,
• geliştirme servislerini yüklemek,
• debug ayarlarını açmak

isteyebiliriz.

Bunları doğrudan settings.php içerisine yazarsak production ortamına yanlışlıkla taşıma riski oluşur.

Bunun yerine:

web/sites/default/settings.local.php

kullanabiliriz.

Drupal core içerisinde bunun için hazır bir örnek dosya da bulunur:

web/sites/example.settings.local.php

Drupal bu yapıyı özellikle development ve test ortamlarında ana settings.php değerlerini override etmek için sunmaktadır.

settings.local.php Dosyasını Oluşturma

Örnek dosyayı kopyalayabiliriz:

cp web/sites/example.settings.local.php \
   web/sites/default/settings.local.php

Ancak dosyayı oluşturmak tek başına yeterli değildir.

settings.php içerisinde local dosyanın include edildiğinden emin olmamız gerekir.

Genellikle dosyanın alt kısmında buna benzer bir bölüm bulunur:

if (file_exists($app_root . '/' . $site_path . '/settings.local.php')) {
  include $app_root . '/' . $site_path . '/settings.local.php';
}

Bu kodun yaptığı şey basittir:

settings.local.php varsa dosyayı yükler, yoksa normal şekilde devam eder.

Drupal'ın geliştirme dokümantasyonunda da local ayar dosyasının bu yöntemle yüklenmesi önerilmektedir.

Lokal Ortamda CSS ve JavaScript Aggregation Kapatmak

Geliştirme yaparken CSS veya JavaScript dosyasında değişiklik yaptığımız halde tarayıcıda eski sonucu görmek istemeyiz.

Bu nedenle lokal ortamda aggregation kapatılabilir:

$config['system.performance']['css']['preprocess'] = FALSE;
$config['system.performance']['js']['preprocess'] = FALSE;

Bu ayarları settings.php yerine settings.local.php içerisinde tutmak daha mantıklıdır.

Production ortamında ise performans nedeniyle aggregation'ın açık olması genellikle tercih edilir.

Cache Kapatma

Tema veya modül geliştirirken Drupal cache sistemi bazen yaptığımız değişiklikleri hemen görmemizi zorlaştırabilir.

Local geliştirme sırasında belirli cache bin'leri devre dışı bırakılabilir.

Örneğin:

$settings['cache']['bins']['render'] = 'cache.backend.null';
$settings['cache']['bins']['page'] = 'cache.backend.null';
$settings['cache']['bins']['dynamic_page_cache'] = 'cache.backend.null';

Buradaki amaç Drupal'ın ilgili cache katmanları yerine null cache backend kullanmasını sağlamaktır.

Bu ayarlar geliştirme sırasında faydalıdır ancak production ortamında kullanılmamalıdır.

Drupal'ın resmi geliştirme dokümantasyonu da bu ayarları local development senaryosu için göstermektedir.

development.services.yml

settings.local.php ile birlikte sık karşılaşacağımız bir başka dosya:

web/sites/development.services.yml

dosyasıdır.

Local settings içerisinden bu dosya yüklenebilir:

$settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml';

Bu dosya geliştirme ortamında Drupal service container ayarlarını değiştirebilmemizi sağlar.

Örneğin null cache backend burada tanımlanabilir.

Drupal core içerisinde gelen development.services.yml dosyası zaten local development için hazırlanmıştır.

Twig Debug Konusu

Eski Drupal projelerinde Twig debug ayarlarını doğrudan development.services.yml içerisinde görmek oldukça yaygındır.

Örneğin:

parameters:
  twig.config:
    debug: true
    auto_reload: true
    cache: false

Ancak burada Drupal sürümüne dikkat etmek gerekir.

Drupal'ın güncel geliştirme dokümantasyonu, Drupal 10.3 ve sonrasında Twig development ayarlarının yönetim arayüzünden kontrol edilebildiğini ve eski yöntemin her durumda önerilmediğini belirtmektedir.

Bu nedenle eski projelerde gördüğümüz her development.services.yml ayarını yeni projelere doğrudan taşımamak gerekir.

settings.local.php Git'e Eklenmeli mi?

Çoğu projede settings.local.php, geliştiricinin kendi ortamına özel ayarlar içerir.

Örneğin bir geliştiricide:

$settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml';

bulunurken başka bir geliştirici farklı bir local servis kullanabilir.

Bu nedenle genellikle:

settings.local.php

Git'e eklenmez.

Bunun yerine örnek bir dosya tutulabilir:

settings.local.example.php

ve her geliştirici kendi:

settings.local.php

dosyasını oluşturabilir.

Böylece kişisel geliştirme ayarları repository'ye karışmaz.

Ortama Göre Ayar Kullanımı

Drupal projelerinde geliştirme, test ve production ortamlarında aynı ayarların kullanılması her zaman doğru değildir.

Örneğin:

Local
Test
Production

ortamlarını düşünelim.

Local ortamda:

Cache: Kapalı
CSS/JS aggregation: Kapalı
Debug: Açık

olabilir.

Production'da ise:

Cache: Açık
CSS/JS aggregation: Açık
Debug: Kapalı

olmasını isteriz.

settings.local.php gibi ortam bazlı yapıların asıl avantajı burada ortaya çıkar.

Kod aynı kalırken çalışma ortamına göre ayarlar değişebilir.

settings.php Dosyasının İzinleri

Drupal kurulumu sırasında settings.php yazılabilir hale getirilebilir. Ancak kurulum bittikten sonra dosyanın web sunucusu tarafından gereksiz yere değiştirilebilir durumda bırakılması önerilmez.

Drupal'ın kendi default.settings.php dosyasında da kurulum sonrasında dosyanın tekrar korunması gerektiği özellikle belirtilmektedir.

Dosyanın mevcut izinlerini:

ls -l web/sites/default/settings.php

komutuyla kontrol edebiliriz.

Örneğin:

-r--r----- settings.php

gibi bir çıktı dosyanın yazma yetkisinin sınırlandırıldığını gösterir.

Tam olarak hangi owner ve permission değerlerinin kullanılacağı ise sunucunun Nginx/Apache, PHP-FPM ve deployment kullanıcı yapısına göre belirlenmelidir.

settings.php İçerisinde Şifre Tutarken Dikkat

Aşağıdaki yapı teknik olarak çalışır:

'password' => 'my-production-password',

ancak settings.php Git repository içerisinde tutuluyorsa production şifresi de repository'ye girmiş olur.

Daha iyi bir yaklaşım şifreyi dışarıdan almaktır.

Örneğin:

'password' => getenv('DB_PASSWORD'),

ve sunucu üzerinde:

DB_PASSWORD="..."

şeklinde tanımlanabilir.

Daha hassas projelerde environment variable yerine secret management araçları veya document root dışında tutulan özel dosyalar da kullanılabilir.

Cache Temizlemeyi Unutmayalım

settings.php, settings.local.php veya service container ayarlarında değişiklik yaptıktan sonra bazı değişikliklerin etkili olması için cache rebuild gerekebilir.

Drush kullanıyorsak:

vendor/bin/drush cr

çalıştırabiliriz.

Özellikle development.services.yml veya container ayarlarında değişiklik yaptıysak cache rebuild yapmak önemlidir.

Örnek settings.php Yapısı

Basit bir proje için ilgili bölümleri bir araya getirirsek aşağıdakine benzer bir yapı oluşabilir:

$databases['default']['default'] = [
  'database' => getenv('DB_NAME'),
  'username' => getenv('DB_USER'),
  'password' => getenv('DB_PASSWORD'),
  'host' => getenv('DB_HOST') ?: 'localhost',
  'driver' => 'mysql',
];

$settings['trusted_host_patterns'] = [
  '^example\.com$',
  '^www\.example\.com$',
];

$settings['config_sync_directory'] = '../config/sync';

if (file_exists($app_root . '/' . $site_path . '/settings.local.php')) {
  include $app_root . '/' . $site_path . '/settings.local.php';
}

Bu örnekte veritabanı bilgilerini environment üzerinden alıyoruz, siteye erişebilecek domainleri sınırlandırıyoruz, configuration dizinini web root dışına taşıyoruz ve varsa local geliştirme ayarlarını yüklüyoruz.

Sonuç

Drupal'da settings.php yalnızca veritabanı şifresinin bulunduğu bir dosya değildir. Siteye ve çalışma ortamına özel pek çok temel ayar burada yönetilir.

Production ortamında özellikle:

• veritabanı bilgileri,
• trusted_host_patterns,
• config_sync_directory,
• hash_salt,
• dosya izinleri

kontrol edilmelidir.

Local geliştirmede ise production ayarlarını değiştirmek yerine settings.local.php kullanmak daha temiz bir yapı sağlar.

Bu ayrım sayesinde aynı Drupal kod tabanını development, test ve production ortamlarında kullanabilir, yalnızca ortamın ihtiyaç duyduğu ayarları değiştirebiliriz.

Son güncelleme: 18.09.2026 14:48