include وrequire في PHP: تحميل ملفات PHP أخرى

تشغّل include 'header.php'; شيفرة ملف PHP آخر في ذلك الموضع من السكربت، كأنها ملصقة هناك. وتفعل require 'header.php'; الشيء نفسه، لكن إذا تعذر تحميل الملف، توقف require السكربت بخطأ فادح بينما تكتفي include بطباعة تحذير وتكمل. والاستخدام الأول المعتاد ترويسة وتذييل تتشاركهما كل الصفحات.

تكتب الكتلة header.php وfooter.php أولًا، ليوجد ما يُضمَّن. شغّلها وانظر إلى تبويب Page:

<?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';

الملفات المُضمَّنة ملفات PHP عادية: يمكن أن تحتوي HTML مع وسوم <?= ?>، وترى المتغير $title المضبوط قبل require. غيّر العنوان وشغّله مرة أخرى؛ وكل صفحة تتطلب الترويسة ستلتقط أي تغيير في ذلك الملف الواحد.

include مقابل require

الفرق الوحيد هو ما يحدث حين يكون الملف مفقودًا أو غير قابل للقراءة. تطبع include تحذيرين، وتكون قيمتها false، ويكمل السكربت:

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

وتطبع require التحذير نفسه ثم ترمي Error، ينهي السكربت ما لم يلتقطه شيء:

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

لذا استخدم require لكل ما لا تعمل الصفحة دونه (الإعدادات، ومكتبات الدوال، وملفات الأصناف) وinclude للأجزاء الاختيارية. وللجزء الذي قد يغيب لسبب مشروع، افحص وجوده أولًا بدل الاعتماد على التحذير:

<?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";
    }
}

المخرجات:

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

include_once وrequire_once

الملف الذي يعرّف دالة أو صنفًا لا يمكن تحميله إلا مرة واحدة: تحميله مرة ثانية خطأ فادح، لأن الدالة موجودة أصلًا.

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

يحدث ذلك حالما يتطلب ملفان كلاهما require 'helpers.php'. تتذكر require_once وinclude_once الملفات التي حُمّلت من قبل وتتخطاها في المرة الثانية، معيدة true:

<?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";

المخرجات:

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

استخدم صيغ _once للملفات التي تصرّح بأشياء، وinclude العادية للقوالب التي تريد إخراجها أكثر من مرة. وفي المشاريع التي تستخدم Composer، يحمّل المحمّل التلقائي ملفات الأصناف نيابة عنك، فتختفي معظم استدعاءات require_once للأصناف؛ راجع Composer.

إعادة قيمة من ملف مُضمَّن

توقف return في المستوى الأعلى من ملف مُضمَّن ذلك الملف وتعيد قيمة إلى تعبير include أو require. وهذا يصنع ملف إعدادات نظيفًا: لا متغيرات عامة، بل قيمة تسندها إلى أي اسم تريده.

<?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']);

المخرجات:

My Shop
shop
bool(false)

تعمل ملفات إعدادات Laravel (config/app.php وconfig/database.php وبقيتها) بهذه الطريقة.

المتغيرات والنطاق في الملفات المُضمَّنة

تعمل الشيفرة المُضمَّنة في نطاق السطر الذي يضمّنها. في أعلى السكربت ترى كل متغير عام؛ وداخل دالة لا ترى إلا المتغيرات المحلية لتلك الدالة. وهذه القاعدة الثانية هي طريقة عمل عارض قوالب صغير: دالة متغيراتها المحلية هي بالضبط المتغيرات التي يجب أن يراها القالب.

<?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],
]);

يعرض تبويب Page القائمتين، مرسومتين من ملف قالب واحد. ولأن include تعمل داخل render()، يرى القالب $heading و$products لكن لا يرى $secret. وصيغة foreach ... endforeach المستخدمة في القالب هي الصيغة البديلة التي تقدمها PHP لقوالب HTML.

مسارات التضمين و__DIR__

لا يُحل مسار مثل 'helper.php' نسبةً إلى الملف الذي يحتوي include. تبحث PHP في إعداد include_path (الذي يبدأ عادة بـ .، مجلد العمل الحالي) ثم فقط في مجلد الملف المُضمِّن نفسه. لذا داخل partials/nav.php، قد تحمّل include 'helper.php' ملف helper.php مختلفًا تمامًا من جذر المشروع. ويزيل __DIR__، مجلد الملف الحالي، التخمين:

<?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';

المخرجات:

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

اكتب كل تضمين على شكل __DIR__ . '/relative/path.php'. فمجلد العمل يعتمد على طريقة بدء السكربت (خادم الويب، أو مهمة cron، أو سطر الأوامر من مجلد آخر)، لكن __DIR__ لا يتغير أبدًا.

لا تضمّن أبدًا ملفًا يسمّيه المستخدم

من أوائل الموجّهات الشائعة قراءة اسم الصفحة من الرابط: include $_GET['page'] . '.php';. وهذا يتيح للزائر اختيار أي ملف على الخادم يعمل، مثل ?page=../../config (تضمين ملف محلي)، ومع الإعدادات القديمة حتى ملفًا من خادم آخر. اربط الأسماء المسموحة بالملفات بدلًا من ذلك. شغّل الكتلة وانقر على الروابط: كل نقرة تشغّل السكربت من جديد مع $_GET['page'] مختلفة.

<?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;
}

لا يمكن أن يصل إلى require إلا الأسماء الثلاثة في $pages؛ ويحصل رابط ../secret على صفحة "Not found". وقراءة قيم الطلب بأمان مشروحة في $_GET و$_POST.