PHP 包含文件 - include 和 require

在PHP开发中，文件包含是实现代码重用和模块化的重要技术。通过包含文件，您可以在多个脚本中重用相同的代码，提高开发效率和维护性。

PHP include 和 require 语句

PHP提供了四个文件包含语句，用于在执行流中插入其他文件的内容：

语句 描述 错误处理
include 包含并运行指定文件 文件不存在时产生警告(E_WARNING)，脚本继续执行
require 包含并运行指定文件 文件不存在时产生致命错误(E_COMPILE_ERROR)，脚本停止执行
include_once 与include相同，但会检查是否已经包含过 文件不存在时产生警告，脚本继续执行
require_once 与require相同，但会检查是否已经包含过 文件不存在时产生致命错误，脚本停止执行

使用场景建议：

  • 对于模板文件、页头、页脚等非关键文件，使用 include
  • 对于配置文件、核心函数库等关键文件，使用 require
  • 当需要避免重复包含时，使用 include_once 或 require_once

基本语法

<?php
// 基本语法
include 'filename.php';
require 'filename.php';
include_once 'filename.php';
require_once 'filename.php';

// 也可以使用括号
include('filename.php');
require('filename.php');
?>

基础实例

1. 包含页头文件

假设有一个标准的页头文件 "header.php"：

header.php 文件内容：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>我的网站</title>
    <link rel="stylesheet" href="styles.css">
</head>
<body>
    <header>
        <h1>欢迎来到我的网站</h1>
        <nav>
            <ul>
                <li><a href="index.php">首页</a></li>
                <li><a href="about.php">关于我们</a></li>
                <li><a href="contact.php">联系我们</a></li>
            </ul>
        </nav>
    </header>
    <main>

index.php 文件使用include：

<?php include 'header.php'; ?>

<section>
    <h2>最新内容</h2>
    <p>这里是网站的最新内容...</p>
</section>

<?php include 'footer.php'; ?>

2. 包含菜单文件

menu.php 文件内容：

<?php
$menuItems = [
    'home' => ['url' => 'index.php', 'text' => '首页'],
    'about' => ['url' => 'about.php', 'text' => '关于'],
    'services' => ['url' => 'services.php', 'text' => '服务'],
    'contact' => ['url' => 'contact.php', 'text' => '联系']
];
?>

<nav class="main-menu">
    <ul>
        <?php foreach ($menuItems as $item): ?>
            <li><a href="<?= $item['url'] ?>"><?= $item['text'] ?></a></li>
        <?php endforeach; ?>
    </ul>
</nav>

在页面中使用菜单：

<!DOCTYPE html>
<html>
<head>
    <title>我的网站</title>
</head>
<body>
    <div class="sidebar">
        <?php include 'menu.php'; ?>
    </div>

    <div class="content">
        <h1>欢迎来到我的网站</h1>
        <p>这里是网站的主要内容...</p>
    </div>
</body>
</html>

3. 变量共享示例

config.php 配置文件：

<?php
// 配置文件
$site_name = "我的网站";
$admin_email = "admin@example.com";
$max_upload_size = 5 * 1024 * 1024; // 5MB

// 数据库配置
$db_host = "localhost";
$db_user = "username";
$db_pass = "password";
$db_name = "my_database";

// 网站设置
$theme = "default";
$language = "zh-CN";
?>

使用配置文件的页面：

<?php require 'config.php'; ?>

<!DOCTYPE html>
<html lang="<?= $language ?>">
<head>
    <meta charset="UTF-8">
    <title><?= $site_name ?></title>
    <link rel="stylesheet" href="themes/<?= $theme ?>/style.css">
</head>
<body>
    <header>
        <h1><?= $site_name ?></h1>
        <p>联系管理员: <?= $admin_email ?></p>
    </header>

    <main>
        <?php
        echo "当前主题: " . $theme . "<br>";
        echo "最大上传大小: " . ($max_upload_size / 1024 / 1024) . " MB";
        ?>
    </main>
</body>
</html>

include 和 require 的区别

错误处理对比：

<?php
// include 示例 - 文件不存在时产生警告，但脚本继续执行
echo "脚本开始执行...<br>";

include 'nonexistent_file.php';  // 会产生警告，但继续执行

echo "这行代码仍然会执行，因为include只产生警告<br>";

// require 示例 - 文件不存在时产生致命错误，脚本停止
echo "准备包含关键文件...<br>";

require 'essential_config.php';  // 如果文件不存在，会产生致命错误

echo "这行代码不会执行，因为require错误是致命的<br>";
?>

实际输出：

脚本开始执行...
Warning: include(nonexistent_file.php): failed to open stream: No such file or directory in...
这行代码仍然会执行，因为include只产生警告
准备包含关键文件...
Fatal error: require(): Failed opening required 'essential_config.php' in...

include_once 和 require_once

这些语句会检查文件是否已经被包含过，如果是则不会再次包含，避免重复定义错误。

functions.php 文件：

<?php
// 函数定义文件
function calculateTotal($price, $quantity) {
    return $price * $quantity;
}

function formatCurrency($amount) {
    return "¥" . number_format($amount, 2);
}

// 如果这个文件被多次包含，下面的常量定义会导致错误
define('SITE_NAME', '我的商城');
?>

正确使用示例：

<?php
// 使用 require_once 避免重复包含
require_once 'functions.php';

// 在另一个地方再次包含（不会实际执行）
require_once 'functions.php';

// 使用函数
$total = calculateTotal(99.99, 3);
echo "总金额: " . formatCurrency($total);
echo "<br>网站名称: " . SITE_NAME;

// 如果使用普通的require，第二次包含会导致常量重定义错误
?>

文件路径处理

PHP支持多种路径引用方式：

<?php
// 相对路径（相对于当前脚本）
include 'includes/header.php';
include './config/database.php';
include '../lib/functions.php';

// 绝对路径
include '/var/www/html/includes/config.php';

// 使用 $_SERVER['DOCUMENT_ROOT'] 获取网站根目录
include $_SERVER['DOCUMENT_ROOT'] . '/includes/header.php';

// 使用 dirname(__FILE__) 获取当前文件所在目录
include dirname(__FILE__) . '/../config/settings.php';

// 使用 __DIR__ 魔术常量（PHP 5.3+）
include __DIR__ . '/../vendor/autoload.php';
?>

路径解析示例：

<?php
// 项目结构示例
// /var/www/html/
//   index.php
//   includes/
//     header.php
//     config/
//       database.php
//   lib/
//     utils.php

// 在 index.php 中包含文件
echo "当前文件: " . __FILE__ . "<br>";
echo "当前目录: " . __DIR__ . "<br>";
echo "文档根目录: " . $_SERVER['DOCUMENT_ROOT'] . "<br>";

// 包含同级目录文件
include 'includes/header.php';

// 包含子目录文件
include 'includes/config/database.php';

// 包含父级目录文件
include '../lib/utils.php';  // 注意：这取决于index.php的位置

// 最佳实践：使用绝对路径
include __DIR__ . '/includes/header.php';
include __DIR__ . '/includes/config/database.php';
?>

实际应用场景

1. MVC模式中的视图包含

<?php
// 在MVC框架中，通常这样组织视图文件

// 基础布局文件 layout.php
?>
<!DOCTYPE html>
<html>
<head>
    <title><?= $title ?? '默认标题' ?></title>
    <?php include 'partials/head_assets.php'; ?>
</head>
<body>
    <?php include 'partials/header.php'; ?>

    <main class="container">
        <?php include $content_view; ?>
    </main>

    <?php include 'partials/footer.php'; ?>
</body>
</html>

2. 模块化组件系统

<?php
// 动态加载组件
function loadComponent($componentName, $data = []) {
    $componentFile = __DIR__ . '/components/' . $componentName . '.php';

    if (file_exists($componentFile)) {
        // 将数据提取到当前符号表
        extract($data);
        include $componentFile;
    } else {
        echo "<!-- 组件 {$componentName} 未找到 -->";
    }
}

// 使用组件
loadComponent('user_card', [
    'name' => '张三',
    'email' => 'zhangsan@example.com',
    'avatar' => 'avatars/zhangsan.jpg'
]);

loadComponent('product_grid', [
    'products' => $products,
    'columns' => 4
]);
?>

3. 配置管理系统

<?php
// 自动加载环境特定的配置文件
$environment = getenv('APP_ENV') ?: 'production';

// 加载基础配置
require_once 'config/base.php';

// 加载环境特定配置
$envConfigFile = "config/environments/{$environment}.php";
if (file_exists($envConfigFile)) {
    require_once $envConfigFile;
} else {
    die("环境配置文件不存在: {$envConfigFile}");
}

// 加载本地覆盖配置（如果存在）
if (file_exists('config/local.php')) {
    require_once 'config/local.php';
}

// 现在可以使用所有配置变量
echo "数据库主机: " . DB_HOST . "<br>";
echo "调试模式: " . (DEBUG_MODE ? '开启' : '关闭') . "<br>";
?>

最佳实践和注意事项

安全注意事项

  • 永远不要包含用户提供的文件路径
  • 使用白名单验证要包含的文件
  • 避免使用动态包含，除非经过严格验证
<?php
// ❌ 危险：直接使用用户输入
$page = $_GET['page']; // 用户可能输入 '../../etc/passwd'
include $page . '.php';

// ✅ 安全：使用白名单
$allowedPages = ['home', 'about', 'contact'];
$page = $_GET['page'] ?? 'home';

if (in_array($page, $allowedPages)) {
    include "pages/{$page}.php";
} else {
    include "pages/404.php";
}

// ✅ 更安全：使用basename防止目录遍历
$page = basename($_GET['page'] ?? 'home');
$pageFile = "pages/{$page}.php";

if (file_exists($pageFile) && is_file($pageFile)) {
    include $pageFile;
} else {
    include "pages/404.php";
}
?>

性能优化建议：

  • 对于频繁包含的文件，考虑使用OPcache
  • 避免在循环中包含文件
  • 使用require_once代替多个require调用
  • 考虑使用自动加载机制替代大量include语句
上一章:PHP Date() 函数 下一章:PHP 文件