PHP include와 require: 다른 PHP 파일 불러오기

include 'header.php';는 스크립트의 그 지점에서 다른 PHP 파일의 코드를 실행하며, 마치 거기에 붙여 넣은 것처럼 동작합니다. require 'header.php';도 같은 일을 하지만, 파일을 불러올 수 없으면 require는 치명적 에러로 스크립트를 멈추고 include는 경고만 출력하고 계속 진행합니다. 가장 흔한 첫 용도는 모든 페이지가 공유하는 헤더와 푸터입니다.

이 블록은 포함할 파일이 있도록 먼저 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을 담을 수 있고, require 전에 설정된 $title 변수를 봅니다. 제목을 바꾸고 다시 실행해 보세요. 헤더를 require하는 모든 페이지가 그 파일 하나의 변경을 반영합니다.

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

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'로 쓰세요. 작업 디렉터리는 스크립트가 어떻게 시작되었는지(웹 서버, cron 작업, 다른 폴더에서의 명령줄)에 따라 달라지지만 __DIR__는 절대 바뀌지 않습니다.

사용자가 지정한 파일은 절대 include하지 말 것

흔한 첫 라우터는 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에서 다룹니다.