Altın Konu PHP Projelerinde Dış Dosya Kullanımı: include ve require Rehberi

[Agora Metin2]

Bir PHP dosyasındaki kodları, başka bir PHP dosyasının içine sanki o satıra yazılmış gibi dahil etmek için include 'header.php'; komutu kullanılır. Aynı işlem require 'header.php'; ile de yapılabilir; aralarındaki temel fark, dosyanın bulunamaması durumunda ortaya çıkar. require kullanımında sistem kritik bir hata vererek çalışmayı tamamen durdururken, include sadece bir uyarı verir ve kodun geri kalanını çalıştırmaya devam eder. Bu yöntem genellikle her sayfada ortak olan alt ve üst bölümleri (header/footer) yönetmek için tercih edilir.

Aşağıdaki örnekte öncelikle header.php ve footer.php dosyaları oluşturulmaktadır. Kodu çalıştırdığınızda sonuçları inceleyebilirsiniz:

<?php
file_put_contents('header.php', <<<'PHP'
<!doctype html>
<html>
<head><title><?= $title ?></title></head>
<body style="font-family: sans-serif">
<nav><a href="?">Home</a> | <a href="?">Shop</a> | <a href="?">Contact</a></nav>
<hr>
PHP);

file_put_contents('footer.php', <<<'PHP'
<hr>
<footer>&copy; <?= date('Y') ?> My Shop</footer>
</body>
</html>
PHP);

$title = 'Welcome';
require 'header.php';
?>
<h1><?= $title ?></h1>
<p>This page is made of three files: header.php, this script, and footer.php.</p>
<?php
require 'footer.php';

Sisteme dahil edilen bu dosyalar standart PHP dosyalarıdır. İçeriklerinde <?= ?> gibi kısa etiketlerle HTML barındırabilirler ve require satırından hemen önce tanımlanmış olan $title gibi değişkenlere erişebilirler. Başlık bilgisini tek bir dosyadan değiştirmeniz, bu dosyayı çağıran tüm sayfalarda değişikliğin geçerli olmasını sağlar.

include ile require Arasındaki Farklar

Bu iki yapı arasındaki yegane ayrım, dosyanın eksik veya ulaşılamaz olduğu senaryolarda görülür. include fonksiyonu iki uyarı mesajı yayınlar, false değerini döndürür ve betiği kesmeden sürdürür:

Warning: include(sidebar.php): Failed to open stream: No such file or directory in /home/index.php on line 2

Warning: include(): Failed opening 'sidebar.php' for inclusion (include_path='.:/usr/share/php83') in /home/index.php on line 2

Buna karşın require, uyarı mesajından sonra -eğer özel bir hata yakalayıcı yoksa- işlemi sonlandıran bir Error fırlatır:

PHP Warning:  require(config.php): Failed to open stream: No such file or directory in /home/index.php on line 2
PHP Fatal error:  Uncaught Error: Failed opening required 'config.php' (include_path='.:/usr/share/php83') in /home/index.php:2

Bu nedenle; sistemin çalışması için zorunlu olan ayar dosyaları, fonksiyon kütüphaneleri veya sınıf tanımlamaları için require kullanmalısınız. İsteğe bağlı görünümler için ise include uygundur. Mevcut olmayabilecek bir dosya için hata uyarısına güvenmek yerine, manuel bir kontrol yapmanız daha sağlıklıdır:

<?php
file_put_contents('banner.php', '<?php echo "Spring sale: 20% off\n";');

foreach (['banner.php', 'sidebar.php'] as $part) {
    if (is_file($part)) {
        $result = include $part;
        echo "$part included, include returned ";
        var_dump($result);
    } else {
        echo "$part not found, skipped\n";
    }
}

Çıktı:

Spring sale: 20% off
banner.php included, include returned int(1)
sidebar.php not found, skipped

include_once ve require_once Kullanımı

Bir sınıfa veya fonksiyona ait tanımlamaların bulunduğu dosyalar sistemde yalnızca bir kez çağrılmalıdır. Aynı tanımı içeren bir dosyanın ikinci kez yüklenmesi, "fonksiyon zaten mevcut" hatasına yol açarak yazılımın çökmesine neden olur.

Fatal error: Cannot redeclare greet() (previously declared in /home/helpers.php:2) in /home/helpers.php on line 2

Bu durum genellikle iki farklı dosyanın aynı anda require 'helpers.php' yapmasıyla tetiklenir. require_once ve include_once komutları, hangi dosyaların daha önce yüklendiğini takip eder. Eğer dosya zaten yüklenmişse, ikinci çağrıda true döndürerek işlemi atlar:

<?php
file_put_contents('helpers.php', <<<'PHP'
<?php
function greet(string $name): string
{
    return "Hello, $name";
}
PHP);

var_dump(require_once 'helpers.php');   // loaded: 1
var_dump(require_once 'helpers.php');   // already loaded: true, skipped
var_dump(include_once 'helpers.php');   // the same list for both

echo greet('Ada'), "\n";

Çıktı:

int(1)
bool(true)
bool(true)
Hello, Ada

Tanımlama içeren dosyalarınız için _once ekini tercih edin; ancak sayfa içinde defalarca tekrarlanabilecek tema parçaları için standart include kullanmaya devam edin. Composer tabanlı modern projelerde, sınıf dosyaları "autoload" mekanizması ile otomatik yüklendiği için require_once ihtiyacı büyük oranda ortadan kalkmıştır.

Dahil Edilen Dosyadan Veri Alma

Dışarıdan çağrılan bir dosyanın içinde kullanılan return ifadesi, o dosyanın çalışmasını durdurur ve sonucu kendisini çağıran include veya require komutuna iletir. Bu yöntem, global değişken karmaşasına girmeden temiz yapılandırma dosyaları oluşturmanıza olanak tanır.

<?php
file_put_contents('config.php', <<<'PHP'
<?php
return [
    'site'     => 'My Shop',
    'currency' => 'EUR',
    'debug'    => false,
    'db'       => ['host' => 'localhost', 'name' => 'shop'],
];
PHP);

$config = require 'config.php';

echo $config['site'], "\n";
echo $config['db']['name'], "\n";
var_dump($config['debug']);

Çıktı:

My Shop
shop
bool(false)

Popüler frameworklerden Laravel, ayar dosyalarını (örneğin config/app.php) bu mantıkla yönetir.

Değişkenlerin Etki Alanı ve Kapsamı

Dahil edilen kodlar, çağrıldıkları satırın geçerli kapsamını (scope) miras alır. Eğer dosya ana dizinde çağrılırsa tüm global değişkenlere erişebilir; bir fonksiyonun içinden çağrılırsa yalnızca o fonksiyonun yerel değişkenlerini görür. Bu özellik, şablon motorlarının temelini oluşturur:

<?php
file_put_contents('product-list.php', <<<'PHP'
<h2><?= htmlspecialchars($heading) ?></h2>
<ul>
<?php foreach ($products as $name => $price): ?>
    <li><?= htmlspecialchars($name) ?>: <?= number_format($price, 2) ?> EUR</li>
<?php endforeach; ?>
</ul>
<p><?= count($products) ?> products</p>
PHP);

function render(string $template, array $vars): string
{
    extract($vars);       // $vars['heading'] becomes $heading
    ob_start();           // capture the output instead of printing it
    include $template;
    return ob_get_clean();
}

$secret = 'not visible inside the template';

echo render('product-list.php', [
    'heading'  => 'Fruit',
    'products' => ['Apple' => 0.5, 'Mango' => 1.75, 'Cherries' => 4.2],
]);
echo render('product-list.php', [
    'heading'  => 'Tea',
    'products' => ['Sencha' => 6, 'Earl Grey' => 4.5],
]);

Yukarıdaki kodu çalıştırdığınızda, aynı şablondan iki farklı liste üretildiğini görebilirsiniz. include işlemi render() fonksiyonu içinde gerçekleştiği için şablon dosyası $heading ve $products verilerini görebilirken, dışarıdaki $secret değişkenine erişemez.

Dosya Yolları ve __DIR__ Sabiti

PHP'de 'helper.php' gibi yalın bir yol kullanıldığında, sistem öncelikle include_path ayarına bakar ve ardından dosyayı çağıran betiğin bulunduğu klasörü kontrol eder. Bu durum, farklı klasörlerdeki dosyaların yanlış dosyaları çağırmasına neden olabilir. Bu karmaşayı önlemek için dosyanın bulunduğu tam dizini veren __DIR__ sabiti kullanılmalıdır:

<?php
mkdir('partials');
file_put_contents('helper.php', '<?php echo "loaded the root helper.php\n";');
file_put_contents('partials/helper.php', '<?php echo "loaded partials/helper.php\n";');

file_put_contents('partials/nav.php', <<<'PHP'
<?php
include 'helper.php';                 // searched from the working directory
include __DIR__ . '/helper.php';      // always the file next to nav.php
echo "__DIR__ in nav.php is ", basename(__DIR__), "\n";
PHP);

include 'partials/nav.php';

Çıktı:

loaded the root helper.php
loaded partials/helper.php
__DIR__ in nav.php is partials

Dosyalarınızı her zaman __DIR__ . '/alt-klasor/dosya.php' biçiminde çağırın. Bu sayede projenin çalışma dizini (terminalden veya webden) değişse bile dosya yollarınız asla bozulmaz.

Güvenlik Uyarısı: Kullanıcı Girdisiyle Dosya Çağırma

Sık yapılan hatalardan biri, URL'den gelen veriyi doğrudan dosya çağırmak için kullanmaktır: include $_GET['page'] . '.php';. Bu açık, saldırganların ?page=../../gizli-dosya gibi yöntemlerle sunucudaki kritik dosyalara erişmesine (Local File Inclusion) yol açabilir. Bunun yerine, sadece izin verilen dosya adlarını içeren bir liste (whitelist) kullanmalısınız:

<?php
file_put_contents('home.php', '<h2>Home</h2><p>Welcome to the shop.</p>');
file_put_contents('about.php', '<h2>About</h2><p>We sell fruit since 1999.</p>');
file_put_contents('contact.php', '<h2>Contact</h2><p>hello@example.com</p>');

$pages = [
    'home'    => 'home.php',
    'about'   => 'about.php',
    'contact' => 'contact.php',
];

$page = $_GET['page'] ?? 'home';
$file = $pages[$page] ?? null;
if ($file === null) {
    http_response_code(404);   // before any output, or the header cannot be sent
}
?>
<nav>
    <a href="?page=home">Home</a> |
    <a href="?page=about">About</a> |
    <a href="?page=contact">Contact</a> |
    <a href="?page=../secret">../secret</a>
</nav>
<?php
if ($file === null) {
    echo '<h2>Not found</h2><p>No page called ', htmlspecialchars($page), '.</p>';
} else {
    require __DIR__ . '/' . $file;
}

Bu örnekte yalnızca $pages dizisinde tanımlı üç sayfa yüklenebilir. Şüpheli bir istek geldiğinde sistem güvenli bir şekilde "Not found" uyarısı verir.

 

[Lightning]

Eline sağlık