PHP include 和 require：加载其他 PHP 文件

include 'header.php'; 会在脚本的当前位置运行另一个 PHP 文件的代码，就像把代码粘贴到这里一样。require 'header.php'; 的作用相同，但如果文件无法加载，require 会以致命错误终止脚本，而 include 只输出一条警告并继续执行。最常见的入门用法是让每个页面共用同一个页头和页脚。

这段代码先写入 header.php 和 footer.php，这样就有文件可以引入了。运行它，然后看看“页面”标签页：

<?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，也能看到在 require 之前设置的 $title 变量。修改标题再运行一次；只要改动这一个文件，每个引入了页头的页面都会随之更新。

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

“页面”标签页显示了用同一个模板文件渲染出的两个列表。因为 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

每个 include 都写成 __DIR__ . '/relative/path.php'。工作目录取决于脚本是怎么启动的（Web 服务器、cron 任务、从其他文件夹在命令行中运行），但 __DIR__ 永远不变。

绝不要引入由用户指定的文件

常见的第一个路由器会从 URL 中读取页面名：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;
}

只有 $pages 中的三个名字才可能到达 require；../secret 链接得到的是“Not found”页面。安全读取请求值的方法见 $_GET 和$_POST。