include ו-require ב-PHP: טעינת קובצי PHP אחרים

include 'header.php'; מריצה את הקוד של קובץ PHP אחר בנקודה הזו בסקריפט, כאילו הוא הודבק שם. require 'header.php'; עושה את אותו הדבר, אבל אם אי אפשר לטעון את הקובץ, require עוצרת את הסקריפט עם שגיאה קטלנית בעוד include רק מדפיסה אזהרה וממשיכה. השימוש הראשון הרגיל הוא header ו-footer שמשותפים לכל הדפים.

הבלוק כותב קודם את 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. שנו את הכותרת והריצו שוב; כל דף שעושה require ל-header היה מקבל שינוי בקובץ האחד הזה.

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, ה-autoloader טוען בשבילכם קובצי מחלקות, ולכן קריאות 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 והשאר) עובדים כך.

משתנים וטווח בקבצים שנכללו

קוד שנכלל רץ בטווח של השורה שכוללת אותו. בראש סקריפט הוא רואה כל משתנה גלובלי; בתוך פונקציה הוא רואה רק את המשתנים המקומיים של הפונקציה הזו. הכלל השני הוא האופן שבו renderer תבניות זעיר עובד: פונקציה שהמשתנים המקומיים שלה הם בדיוק המשתנים שהתבנית צריכה לראות.

<?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.

נתיבי include ו-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

כתבו כל include כ-__DIR__ . '/relative/path.php'. תיקיית העבודה תלויה באופן שבו הסקריפט הופעל (שרת ה-web, משימת cron, שורת הפקודה מתיקייה אחרת), אבל __DIR__ אף פעם לא משתנה.

לעולם אל תכללו קובץ שהמשתמש קבע את שמו

נתב ראשון נפוץ קורא את שם הדף מכתובת ה-URL: include $_GET['page'] . '.php';. זה מאפשר למבקר לבחור איזה קובץ בשרת ירוץ, למשל ?page=../../config (local file inclusion), ועם הגדרות ישנות אפילו קובץ משרת אחר. מפו במקום זאת שמות מותרים לקבצים. הריצו את הבלוק ולחצו על הקישורים: כל לחיצה מריצה את הסקריפט שוב עם $_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;
}

רק שלושת השמות שב-$pages יכולים להגיע אי פעם ל-require; הקישור ../secret מקבל את דף ה-"Not found". קריאה בטוחה של ערכי בקשה מוסברת ב-$_GET ו-$_POST.