include và require trong PHP: nạp file PHP khác

include 'header.php'; chạy code của một file PHP khác tại đúng vị trí đó trong script, như thể nó được dán vào. require 'header.php'; làm điều tương tự, nhưng nếu không nạp được file thì require dừng script với lỗi nghiêm trọng, còn include chỉ in ra cảnh báo rồi chạy tiếp. Cách dùng đầu tiên thường gặp là phần header và footer dùng chung cho mọi trang.

Khối code này ghi header.php và footer.php trước, để có file mà include. Chạy nó rồi xem tab Trang:

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

Các file được include là file PHP bình thường: chúng có thể chứa HTML với thẻ <?= ?>, và thấy được biến $title được gán trước lệnh require. Đổi tiêu đề rồi chạy lại; mọi trang require header đều nhận thay đổi khi bạn sửa đúng một file đó.

include và require

Khác biệt duy nhất là chuyện gì xảy ra khi file bị thiếu hoặc không đọc được. include in ra hai cảnh báo, cho giá trị false, và script chạy tiếp:

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 in ra cùng cảnh báo đó rồi ném ra một Error, khiến script kết thúc trừ khi có code bắt lỗi:

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

Vì vậy, hãy dùng require cho những gì trang không thể chạy thiếu (cấu hình, thư viện hàm, file lớp) và include cho các phần tùy chọn. Với phần có thể vắng mặt một cách hợp lệ, hãy kiểm tra trước thay vì dựa vào cảnh báo:

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

Đầu ra:

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

include_once và require_once

File định nghĩa một hàm hay một lớp chỉ được nạp một lần: nạp lần thứ hai là lỗi nghiêm trọng, vì hàm đã tồn tại.

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

Điều này xảy ra ngay khi hai file cùng require 'helpers.php'. require_once và include_once ghi nhớ những file đã nạp và bỏ qua chúng ở lần thứ hai, trả về 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";

Đầu ra:

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

Dùng dạng _once cho các file khai báo, và include bình thường cho template bạn muốn xuất ra nhiều lần. Trong dự án dùng Composer, autoloader tự nạp file lớp cho bạn, nên các lệnh require_once cho lớp gần như biến mất; xem Composer.

Trả về giá trị từ file được include

Một lệnh return ở cấp cao nhất của file được include sẽ dừng file đó và trả một giá trị về cho biểu thức include hoặc require. Nhờ vậy bạn có một file cấu hình gọn gàng: không có biến toàn cục, chỉ là một giá trị bạn gán cho bất kỳ tên nào bạn muốn.

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

Đầu ra:

My Shop
shop
bool(false)

Các file cấu hình của Laravel (config/app.php, config/database.php và các file khác) hoạt động theo cách này.

Biến và phạm vi trong file được include

Code được include chạy trong phạm vi của dòng include nó. Ở đầu script, nó thấy mọi biến toàn cục; bên trong một hàm, nó chỉ thấy biến cục bộ của hàm đó. Quy tắc thứ hai chính là cách một trình render template nhỏ hoạt động: một hàm có các biến cục bộ đúng bằng những biến mà template cần thấy.

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

Tab Trang hiển thị cả hai danh sách, được render từ cùng một file template. Vì include chạy bên trong render(), template thấy $heading và $products nhưng không thấy $secret. Dạng foreach ... endforeach dùng trong template là cú pháp thay thế mà PHP cung cấp cho template HTML.

Đường dẫn include và DIR

Một đường dẫn như 'helper.php' không được tính tương đối so với file chứa lệnh include. PHP tìm trong thiết lập include_path (thường bắt đầu bằng ., thư mục làm việc hiện tại) và chỉ sau đó mới tìm trong thư mục của chính file đang include. Vì thế bên trong partials/nav.php, include 'helper.php' có thể nạp một helper.php hoàn toàn khác ở thư mục gốc của dự án. __DIR__, thư mục của file hiện tại, giúp bạn khỏi phải đoán:

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

Đầu ra:

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

Hãy viết mọi lệnh include dưới dạng __DIR__ . '/relative/path.php'. Thư mục làm việc phụ thuộc vào cách script được khởi chạy (máy chủ web, cron job, dòng lệnh từ một thư mục khác), nhưng __DIR__ thì không bao giờ thay đổi.

Đừng bao giờ include file do người dùng đặt tên

Một router đầu tay thường đọc tên trang từ URL: include $_GET['page'] . '.php';. Cách này cho phép người truy cập chọn file nào trên máy chủ sẽ chạy, ví dụ ?page=../../config (lỗ hổng local file inclusion), và với thiết lập cũ thì thậm chí cả file từ máy chủ khác. Thay vào đó, hãy ánh xạ các tên được phép sang file. Chạy khối code và bấm vào các liên kết: mỗi lần bấm chạy lại script với một $_GET['page'] khác.

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

Chỉ ba tên trong $pages mới có thể tới được require; liên kết ../secret nhận trang "Not found". Cách đọc giá trị request an toàn được trình bày trong $_GET và$_POST.