PHP’de include ve require Farkı

Web uygulamaları büyüdükçe kod tabanını tek bir dosyada tutmak imkansız hale gelir. Kodun yönetilebilir, okunabilir ve tekrar kullanılabilir olması için parçalara bölünmesi gerekir. PHP, harici dosyaları ana çalışma alanına dahil etmek için iki temel yapı sunar: include ve require.

Görünüşte benzer bir amaca hizmet eden bu iki ifade, dosyanın bulunamaması veya yüklenememesi durumunda gösterdikleri davranış biçimiyle birbirinden ayrılır. Yanlış yapının tercih edilmesi, uygulamanın beklenmedik şekilde çökmesine ya da güvenlik zafiyetlerinin oluşmasına yol açabilir.

include ve require Nedir?

PHP’de include ve require, belirtilen dosyanın içeriğini alarak çalıştığı satıra yerleştiren dil yapılarıdır (language construct). Bu sayede veritabanı bağlantı kodları, fonksiyon kütüphaneleri, başlık (header) veya altbilgi (footer) gibi şablon parçaları tek bir dosyada tutulup ihtiyaç duyulan sayfalara aktarılabilir.

Her iki yapının da temel sözdizimi oldukça basittir. Parantezli veya parantezsiz olarak çağrılabilirler:

include 'ayar.php';
require 'ayar.php';

Kod okunabilirliği açısından genellikle parantezsiz kullanım tercih edilir. Ancak asıl ayrım, çağrılan dosya diskte bulunamadığında ortaya çıkar.

Temel Fark: Hata Yönetimi

include ile require arasındaki en belirgin fark, eksik veya ulaşılamayan bir dosya karşısında PHP motorunun ürettiği hata seviyesidir.

include ile Çalışma Mantığı

include ifadesi, çağrılan dosya bulunamadığında bir uyarı (E_WARNING) üretir. Önemli olan nokta şudur: PHP motoru bu uyarıyı verdikten sonra çalışmayı durdurmaz. Dosyanın altındaki kodlar hiçbir şey olmamış gibi çalışmaya devam eder.

Aşağıdaki örneği inceleyelim:

<?php
echo "Program başlatıldı.n";

include 'olmayan_dosya.php';

echo "Bu satır include sonrasında çalışmaya devam eder.n";
?>

Yukarıdaki kod çalıştırıldığında çıktı şu şekilde olur:

Program başlatıldı.
Warning: include(olmayan_dosya.php): Failed to open stream: No such file or directory in ...
Bu satır include sonrasında çalışmaya devam eder.

Eğer çağrılan dosya yalnızca sayfanın görsel bir parçasını oluşturuyorsa (örneğin yan sütundaki bir reklam alanı), programın çalışmayı sürdürmesi kabul edilebilir. Ancak dosya kritik bir işlem içeriyorsa, bu durum hatalı veri üretimine neden olabilir.

require ile Çalışma Mantığı

require ifadesi ise hedeflenen dosya bulunamadığında ölümcül bir hata (E_COMPILE_ERROR / Fatal Error) fırlatır. Bu hata türü uygulamanın yürütülmesini anında sonlandırır. require ifadesinden sonra gelen hiçbir kod satırı çalıştırılmaz.

Aşağıdaki örneği ele alalım:

<?php
echo "Program başlatıldı.n";

require 'olmayan_dosya.php';

echo "Bu satır asla ekrana yazdırılmayacaktır.n";
?>

Bu betik çalıştırıldığında PHP şu çıktıyı üretir ve anında durur:

Program başlatıldı.
Fatal error: require(): Failed opening required 'olmayan_dosya.php' (include_path='...') in ...

Eğer uygulamanızın çalışması için veritabanı şifreleri, kimlik doğrulama fonksiyonları veya temel konfigürasyon değişkenleri zorunluysa, require tercih edilmelidir. Aksi takdirde, veritabanı bağlantısı kurulamadığı halde çalışmaya devam eden bir betik, kullanıcıya anlamsız hatalar gösterebilir veya tutarsız işlemlere yol açabilir.

include_once ve require_once Varyantları

PHP, bu iki yapıya ek olarak “_once” takısına sahip varyantlar da sunar: include_once ve require_once.

Bu yapılar, hedeflenen dosyanın daha önce betik içinde dahil edilip edilmediğini kontrol eder. Eğer dosya daha önce dahil edilmişse, tekrar yüklenmez ve işlem sessizce atlanır.

Neden _once Kullanılır?

Özellikle fonksiyon veya sınıf tanımlarının bulunduğu kütüphane dosyalarını birden fazla kez dahil etmek ciddi hatalara yol açar. PHP, aynı ada sahip bir fonksiyonun veya sınıfın birden fazla kez tanımlanmasına izin vermez ve “Cannot redeclare function” şeklinde ölümcül bir hata verir.

Aşağıdaki senaryoyu düşünelim:

<?php
// fonksiyonlar.php içeriği
function baglantiKur() {
    return "Bağlantı aktif.";
}
?>

Eğer ana dosyanızda şu şekilde bir yükleme yaparsanız hata alırsınız:

<?php
require 'fonksiyonlar.php';
// Araya giren başka bir dosya da dolaylı olarak fonksiyonlar.php dosyasını çağırıyor olabilir
require 'fonksiyonlar.php'; // Hata: Fatal error: Cannot redeclare baglantiKur()
?>

Bunun yerine require_once kullandığınızda PHP dosyanın daha önce yüklendiğini algılar:

<?php
require_once 'fonksiyonlar.php';
require_once 'fonksiyonlar.php'; // Bu satır güvenle yoksayılır, hata vermez

echo baglantiKur();
?>

Performans Etkisi

include_once ve require_once ifadeleri, dosyanın daha önce açılıp açılmadığını takip etmek için dahili bir kontrol tablosu tutar. Bu durum küçük de olsa bir ek işlem yükü getirir. Büyük ölçekli ve yüksek trafikli sistemlerde yüzlerce dosyanın bu şekilde dahil edilmesi mikro düzeyde performans kaybına yol açabilir. Modern PHP mimarilerinde (Composer tabanlı PSR-4 autoloader gibi) dosyaların otomatik yüklenmesi tercih edildiğinden manuel require_once kullanımı çoğunlukla yalnızca giriş dosyası (index.php) ile sınırlı kalmaktadır.

Hangi Durumda Hangisi Kullanılmalı?

Doğru yapıyı seçmek, uygulamanızın sağlamlığı (robustness) açısından temel bir kuraldır:

• Veritabanı yapılandırmaları, güvenlik anahtarları ve ortam değişkenleri için require veya require_once kullanılmalıdır.
• Sınıf (class), arayüz (interface) ve global fonksiyon dosyaları için require_once kullanılmalıdır.
• Sayfanın genel akışını bozmayacak opsiyonel bileşenler (altbilgi, dinamik widget’lar, tema parçaları) için include kullanılmalıdır.
• Koşula bağlı olarak yüklenecek ve yüklenmemesi halinde varsayılan bir alternatife dönülebilecek dosyalar için include tercih edilmelidir.

Güvenlik Boyutu: Dosya Dahil Etme Zafiyetleri

Bir siber güvenlik perspektifinden bakıldığında include ve require ifadeleri dikkatle ele alınmalıdır. Kullanıcıdan alınan girdilerin (örneğin URL üzerinden gelen $_GET['sayfa'] parametresinin) filtrelenmeden doğrudan bu ifadelere verilmesi, Yerel Dosya Dahil Etme (Local File Inclusion – LFI) veya Uzak Dosya Dahil Etme (Remote File Inclusion – RFI) zafiyetlerine yol açar.

Hatalı ve güvensiz bir örnek:

<?php
// GÜVENSİZ KOD ÖRNEĞİ
$sayfa = $_GET['sayfa'];
include($sayfa . '.php'); 
?>

Bu örnekte saldırgan, sayfa parametresine ../../../../etc/passwd gibi dizin atlama (path traversal) değerleri girerek sunucudaki kritik sistem dosyalarını okuyabilir.

Güvenli bir yaklaşım için:

• Dahil edilecek dosyaları mutlaka statik bir beyaz liste (whitelist) kontrolünden geçirin.
• Kullanıcı girdisini doğrudan dosya yolu olarak kullanmaktan kaçının.
• Dosya yollarını belirlerken __DIR__ sabitini kullanarak göreceli yollar yerine mutlak yollar tanımlayın.

Mutlak yol kullanımı örneği:

<?php
// Daha güvenli ve performanslı mutlak yol kullanımı
require_once __DIR__ . '/yapilandirma/veritabani.php';
?>

__DIR__ sabiti, çalışan dosyanın bulunduğu tam dizin yolunu döndürür. Bu sayede dosya çağrıları PHP’nin include_path ayarlarından etkilenmez ve doğrudan doğru adrese yönelir.

Özet ve Sonraki Adımlar

include ve require arasındaki temel fark hata toleransıdır. require, uygulamanın yaşam döngüsü için zorunlu olan bileşenlerde kullanılır ve eksiklik durumunda çalışmayı durdurur. include ise eksiklik halinde uyarı vererek uygulamanın devam etmesine izin verir. Fonksiyon ve sınıf çakışmalarını önlemek için ise bu yapıların _once varyantları kullanılır.

Uygulamanızda bu mekanizmaları doğru kurguladıktan sonra, kod organizasyonunu daha profesyonel bir seviyeye taşımak adına nesne yönelimli programlama (OOP) ve Composer üzerinden gelen PSR-4 otomatik sınıf yükleme (autoloading) standartlarını inceleyebilirsiniz.