PHP include and require: Load Other PHP Files

include 'header.php'; runs the code of another PHP file at that point in the script, as if it were pasted there. require 'header.php'; does the same, but if the file cannot be loaded, require stops the script with a fatal error while include only prints a warning and continues. The usual first use is a header and footer shared by every page.

The block writes header.php and footer.php first, so there are files to include. Run it and look at the Page tab:

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

The included files are ordinary PHP files: they can contain HTML with <?= ?> tags, and they see the $title variable set before the require. Change the title and run it again; every page that requires the header would pick up a change to that one file.

include vs require

The only difference is what happens when the file is missing or unreadable. include prints two warnings, evaluates to false, and the script continues:

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 prints the same warning and then throws an Error, which ends the script unless something catches it:

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

So use require for anything the page cannot run without (configuration, function libraries, class files) and include for optional parts. For a part that may legitimately be absent, check for it first rather than relying on the warning:

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

Output:

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

include_once and require_once

A file that defines a function or a class can only be loaded once: loading it a second time is a fatal error, because the function already exists.

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

That happens as soon as two files each require 'helpers.php'. require_once and include_once remember which files were already loaded and skip them the second time, returning 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";

Output:

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

Use the _once forms for files that declare things, and plain include for templates you want to output more than once. In projects that use Composer, the autoloader loads class files for you, so require_once calls for classes mostly disappear; see Composer.

Return a value from an included file

A return at the top level of an included file stops that file and hands a value back to the include or require expression. That makes a clean configuration file: no global variables, just a value you assign to whatever name you like.

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

Output:

My Shop
shop
bool(false)

Laravel's configuration files (config/app.php, config/database.php and the rest) work this way.

Variables and scope in included files

Included code runs in the scope of the line that includes it. At the top of a script it sees every global variable; inside a function it sees only that function's local variables. That second rule is how a tiny template renderer works: a function whose locals are exactly the variables the template should see.

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

The Page tab shows both lists, rendered from one template file. Because include runs inside render(), the template sees $heading and $products but not $secret. The foreach ... endforeach form used in the template is the alternative syntax PHP offers for HTML templates.

Include paths and DIR

A path like 'helper.php' is not resolved relative to the file that contains the include. PHP searches the include_path setting (which normally starts with ., the current working directory) and only then the including file's own folder. So inside partials/nav.php, include 'helper.php' can load a completely different helper.php from the project root. __DIR__, the directory of the current file, removes the guesswork:

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

Output:

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

Write every include as __DIR__ . '/relative/path.php'. The working directory depends on how the script was started (the web server, a cron job, the command line from another folder), but __DIR__ never changes.

Never include a file named by the user

A common first router reads the page name from the URL: include $_GET['page'] . '.php';. That lets a visitor choose which file on the server runs, for example ?page=../../config (local file inclusion), and with old settings even a file from another server. Map allowed names to files instead. Run the block and click the links: each click runs the script again with a different $_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;
}

Only the three names in $pages can ever reach require; the ../secret link gets the "Not found" page. Reading request values safely is covered in $_GET and$_POST.