PHP include, require, include_once Arasındaki Farklar Nelerdir?

PHP'de bir dosyanın başka bir betiğe eklenmesi için kullanılan include, require, include_once ve require_once ifadeleri sıkça karıştırılır. Bu makalede bu dört ifadenin davranışlarını, hata yönetimini, performans ve kullanım önerilerini örneklerle açıklayacağım. Amaç, hangi duruma hangi ifadeyi tercih etmeniz gerektiğini pratik ve sürdürülebilir bir bakış açısıyla anlatmaktır.

Giriş: Neden farklı include ifadeleri var?

Bir uygulamada tekrar kullanılabilir kodları (ayarlar, fonksiyonlar, sınıflar, şablon parçaları) başka dosyalarda tutmak, bakımı ve test edilebilirliği kolaylaştırır. Ancak aynı dosyanın beklenmedik şekilde birden fazla kez dahil edilmesi ya da kritik bir dosyanın eksik olması farklı sonuçlar doğurur. PHP bu ihtiyaçlara cevap veren birkaç farklı include mekanizması sağlar.

Temel farklar (özet)

  • include: Belirtilen dosyayı dahil eder. Dosya bulunmazsa uyarı (warning) verir ve betik çalışmaya devam eder.
  • require: include ile aynı şekilde dosyayı dahil eder, ancak dosya bulunmazsa ölümsüz (fatal) hata oluşur ve betik durur.
  • include_once: include ile aynı işlevi görür ama aynı dosyayı birden fazla kez dahil etmez; daha önce dahil edilmişse atlar.
  • require_once: require ile aynı olup, dosya daha önce dahil edilmediyse dahil eder; daha önce eklenmişse atlar. Eksikse fatal hata verir.

Davranış ve hata seviyeleri

Detaylı olarak:

  • include başarısız olduğunda E_WARNING üretir — betik yürütülmeye devam eder. Bu, dahil edilen dosyanın isteğe bağlı olduğu durumlar için yararlıdır (ör. ek özellikler, opsiyonel şablon parçaları).
  • require başarısız olduğunda fatal error üretir (çalışmayı durdurur). Bu, dosyanın uygulama için zorunlu olduğu bootstrap, konfigürasyon veya çekirdek sınıflar için uygundur.
  • include_once / require_once davranışı aynı hata seviyelerini korur, ancak ekleme işleminden önce daha önce dahil edilip edilmediğini kontrol ederler.

Kısa örnekler

include örneği (dosya yoksa script devam eder):

<?php
include 'optional-widget.php';
echo "Devam ediyor\n";
?>

require örneği (dosya yoksa script durur):

<?php
require 'config.php';
// config.php bulunmazsa buraya hiç gelinmez
?>

include_once örneği (aynı dosya tekrar include edilirse atlanır):

<?php
include_once 'helpers.php';
include_once 'helpers.php'; // ikinci include atlanır
?>

Kullanım senaryoları ve en iyi uygulamalar

  • require / require_once — Zorunlu dosyalar (konfigürasyon, autoload bootstrap, temel sınıflar): require veya require_once tercih edin. Hata oluştuğunda uygulamanın baştan durması, eksik kritik bileşenle devam etmekten daha güvenlidir.
  • include / include_once — Opsiyonel içerik (istatistik betikleri, isteğe bağlı widget'lar, templateler): include veya include_once kullanın; uygulamanın çalışmaya devam etmesi isteniyorsa include uygundur.
  • _once versiyonları — Aynı dosyanın birden çok kez eklenmesi sonucu oluşabilecek function/sınıf yeniden tanımlama hatalarını önlemek için kullanılır. Ancak performans maliyeti vardır; büyük, sık çağrılan döngülerde dikkatli olun.
  • Yol belirtme — include/require yaparken göreli yollar yerine mutlak yollar veya __DIR__ sabitini kullanın: require_once __DIR__ . '/config.php'; Bu, dosya yoluyla ilgili sürprizleri azaltır.
  • Autoloading — Sınıflar için include/require kullanmak yerine PSR-4 uyumlu autoloader (composer) kullanmak iyi bir pratiktir. Bu, manuel include/require karmaşasını azaltır.

Performans notu

include_once ve require_once, PHP'nin daha önce dosyayı dahil edip etmediğini kontrol etmek için ek işlem yapar; bu nedenle çok sık ve büyük uygulamalarda küçük bir performans farkı yaratabilir. Kritik performans gerektiren döngüler içinde dosya dahil etmemeye dikkat edin.

Diğer teknik noktalar ve sık yapılan hatalar

  • Değişken kapsamı: include edilen dosya, dahil edildiği betiğin kapsamına erişebilir. Fonksiyon içinde include ederseniz dosya fonksiyonun yerel kapsamında çalışır.
  • Return değeri: include ve require, dahil edilen dosyanın return'ine göre bir değer döndürebilir. Bu şekilde konfigürasyon dizileri gibi veriler geri alınabilir.
  • Dosya yolları: include_path, relatif yollar ve __DIR__ arasındaki farklara dikkat edin. Yanlış yol, beklenmedik include hatalarına yol açar.
  • Çoklu include sonucu redeclare hataları: Fonksiyon veya sınıf tekrar tanımlamaları fatal hataya neden olur. Bu yüzden helper/sınıf dosyalarınızı require_once veya autoload ile koruyun.

Örnek: config dosyası nasıl dahil edilmeli?

Config dosyası uygulama için kritikse:

<?php
require_once __DIR__ . '/config.php';
// config.php yoksa uygulama çalışmaz ve hata verir
?>

Opsiyonel bir modül için:

<?php
if (file_exists(__DIR__ . '/optional-module.php')) {
    include_once __DIR__ . '/optional-module.php';
}
?>

Sonuç

Özetle, require ve include arasındaki temel fark hata yönetimidir: require kritik dosyalar için, include opsiyonel parçalar için kullanılır. _once versiyonları, çoklu dahil edilmenin yol açtığı yeniden tanımlama hatalarını engeller fakat küçük bir performans maliyeti getirir. Modern uygulamalarda sınıflar için autoloading kullanmak ve yolları __DIR__ ile sabitlemek, sürdürülebilir ve güvenli bir yaklaşım sağlar.

Bu bilgilerle hangi include ifadesini ne zaman kullanacağınız daha belirgin olacaktır: kritik kaynaklar için require(_once), opsiyonel içerik için include(_once), ve sınıflar için autoload tercih edin.