萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP 檔案包含機制:include、require、include_once、require_once 差異與最佳實務

檔案包含是 PHP 程式碼模組化、重用的基礎機制。include、require 及其 _once 變體,在錯誤處理、重複包含防護上有關鍵差異。本文完整對比四種函數並提供實務建議。

四大函數差異總覽

函數找不到檔案腳本執行重複包含回傳值效能
include Warning(警告) 繼續執行 允許重複 成功 1,失敗 false 略快
require Fatal Error(致命錯誤) 立即停止 允許重複 無(成功不回傳) 略快
include_once Warning 繼續執行 忽略重複 成功 1,失敗 false 稍慢(需檢查)
require_once Fatal Error 立即停止 忽略重複 無 稍慢

錯誤輸出實例對比

include 錯誤

<?php
include 'missing.php';
echo "Hello World!"; // 仍會執行
?>
// Warning: include(missing.php): Failed to open stream...
// Warning: include(): Failed opening 'missing.php'...
// Hello World!

require 錯誤

<?php
require 'missing.php';
echo "Hello World!"; // 不會執行
?>
// Warning: require(missing.php): Failed to open stream...
// Fatal error: require(): Failed opening required 'missing.php'...
// 腳本終止

實務應用場景

佈局模板:header.php / footer.php

<?php
// views/layout/header.php
?>
<!DOCTYPE html>
<html lang="zh-TW">
<head>
    <meta charset="UTF-8">
    <title><?= $pageTitle ?? 'My Site' ?></title>
</head>
<body>
    <header>
        <nav><a href="/">首頁</a> | <a href="/about">關於</a></nav>
    </header>
    <main>

<?php
// views/layout/footer.php
?>
    </main>
    <footer>© 2024 My Site</footer>
</body>
</html>
<?php
// index.php
$pageTitle = '首頁';
include __DIR__ . '/views/layout/header.php';
?>
    <h1>歡迎來到首頁</h1>
    <p>內容...</p>
<?php
include __DIR__ . '/views/layout/footer.php';
?>

設定檔:config.php

<?php
// config/app.php
return [
    'app' => [
        'name' => 'My App',
        'env' => 'production',
        'debug' => false,
        'url' => 'https://example.com',
    ],
    'db' => [
        'driver' => 'mysql',
        'host' => '127.0.0.1',
        'port' => 3306,
        'database' => 'myapp',
        'username' => 'db_user',
        'password' => 'secret',
        'charset' => 'utf8mb4',
    ],
];
?>
<?php
// 使用
$config = require __DIR__ . '/config/app.php'; // 取得陣列
$pdo = new PDO(
    "{$config['db']['driver']}:host={$config['db']['host']};dbname={$config['db']['database']};charset={$config['db']['charset']}",
    $config['db']['username'],
    $config['db']['password']
);
?>

函數庫:helpers.php

<?php
// helpers.php
function h(string $str): string {
    return htmlspecialchars($str, ENT_QUOTES, 'UTF-8');
}

function url(string $path = ''): string {
    return rtrim($_ENV['APP_URL'] ?? '', '/') . '/' . ltrim($path, '/');
}

function dd(mixed $value): never {
    var_dump($value);
    exit;
}
?>
<?php
require_once __DIR__ . '/helpers.php'; // 全域函數庫用 once 防重複定義錯誤
echo h('<script>alert(1)</script>');
?>

路徑解析規則

  1. 絕對路徑:/var/www/html/config.php、C:\xampp\htdocs\config.php
  2. 相對路徑:相對於當前執行腳本的工作目錄(非包含檔案所在目錄)
  3. include_path:php.ini 設定的搜尋路徑列表
⚠️ 相對路徑陷阱:
// index.php
include 'config.php'; // 正確

// admin/index.php
include 'config.php'; // 錯誤!尋找 admin/config.php
include '../config.php'; // 正確但脆弱
include __DIR__ . '/../config.php'; // ✅ 最佳:相對於當前檔案位置

最佳實務建議

  1. 關鍵依賴用 require_once:設定檔、核心類別、自動載入器、資料庫連線
  2. 版面模板用 include:header、footer、sidebar(缺失不應中斷整頁)
  3. 函數庫用 require_once:防止重複定義致命錯誤
  4. 永遠使用 __DIR__ 建立絕對路徑
  5. 現代專案採用 Composer PSR-4 自動載入:require 'vendor/autoload.php' 後無需手動 include 類別檔
  6. 回傳值而非副作用:設定檔 return [...],類別檔只定義類別

現代框架中的包含機制

<?php
// Laravel Blade 模板繼承
// layouts/app.blade.php
@yield('content')

// pages/home.blade.php
@extends('layouts.app')
@section('content')
    <h1>首頁</h1>
@endsection

// Symfony Twig
// base.html.twig
{% block body %}{% endblock %}

// index.html.twig
{% extends 'base.html.twig' %}
{% block body %}
    <h1>首頁</h1>
{% endblock %}
💡 遷移建議: 純 PHP 專案漸進式導入 Composer 自動載入,建立 src/ 目錄對應命名空間,逐步移除手動 require。模板建議採用 Plates(原生 PHP 模板引擎)或 Twig(功能完整),分離邏輯與視圖。
copyright © 萬盛學電腦網 all rights reserved