include dan require PHP: Memuat File PHP Lain

include 'header.php'; menjalankan kode dari file PHP lain di titik itu dalam script, seolah-olah kodenya ditempel di sana. require 'header.php'; melakukan hal yang sama, tetapi jika file-nya tidak bisa dimuat, require menghentikan script dengan fatal error sedangkan include hanya mencetak warning lalu lanjut. Pemakaian pertama yang paling umum adalah header dan footer yang dipakai bersama oleh setiap halaman.

Blok ini menulis header.php dan footer.php lebih dulu, agar ada file yang bisa di-include. Jalankan dan lihat tab Halaman:

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

File yang di-include adalah file PHP biasa: isinya bisa berupa HTML dengan tag <?= ?>, dan file itu melihat variabel $title yang diisi sebelum require. Ubah judulnya lalu jalankan lagi; setiap halaman yang me-require header akan ikut mendapat perubahan pada satu file itu.

include vs require

Satu-satunya perbedaan adalah apa yang terjadi saat file-nya tidak ada atau tidak bisa dibaca. include mencetak dua warning, bernilai false, dan script lanjut:

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 mencetak warning yang sama lalu melempar Error, yang mengakhiri script kecuali ada yang menangkapnya:

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

Jadi pakai require untuk apa pun yang dibutuhkan halaman agar bisa berjalan (konfigurasi, library fungsi, file class) dan include untuk bagian yang opsional. Untuk bagian yang memang boleh tidak ada, periksa dulu keberadaannya alih-alih mengandalkan 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 dan require_once

File yang mendefinisikan fungsi atau class hanya bisa dimuat sekali: memuatnya untuk kedua kali adalah fatal error, karena fungsinya sudah ada.

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

Hal itu terjadi begitu dua file masing-masing menulis require 'helpers.php'. require_once dan include_once mengingat file mana yang sudah dimuat dan melewatinya pada kali kedua, sambil mengembalikan 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

Pakai bentuk _once untuk file yang mendeklarasikan sesuatu, dan include biasa untuk template yang ingin kamu tampilkan lebih dari sekali. Di proyek yang memakai Composer, autoloader memuat file class untukmu, jadi pemanggilan require_once untuk class sebagian besar hilang; lihat Composer.

Mengembalikan nilai dari file yang di-include

return di level teratas file yang di-include menghentikan file itu dan menyerahkan sebuah nilai ke ekspresi include atau require. Cara ini menghasilkan file konfigurasi yang rapi: tanpa variabel global, hanya sebuah nilai yang bisa kamu simpan dengan nama apa pun.

<?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)

File konfigurasi Laravel (config/app.php, config/database.php, dan lainnya) bekerja dengan cara ini.

Variabel dan scope di file yang di-include

Kode yang di-include berjalan di scope baris yang meng-include-nya. Di bagian atas script, kode itu melihat setiap variabel global; di dalam fungsi, ia hanya melihat variabel lokal fungsi itu. Aturan kedua inilah yang membuat renderer template kecil bisa bekerja: sebuah fungsi yang variabel lokalnya persis variabel-variabel yang boleh dilihat template.

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

Tab Halaman menampilkan kedua list, yang dirender dari satu file template. Karena include berjalan di dalam render(), template itu melihat $heading dan $products tetapi tidak melihat $secret. Bentuk foreach ... endforeach yang dipakai di template adalah sintaks alternatif yang disediakan PHP untuk template HTML.

Path include dan DIR

Path seperti 'helper.php' tidak diselesaikan relatif terhadap file yang berisi include. PHP mencari di pengaturan include_path (yang biasanya diawali ., direktori kerja saat ini) dan baru setelah itu di folder milik file yang meng-include. Jadi di dalam partials/nav.php, include 'helper.php' bisa memuat helper.php yang sama sekali berbeda dari root proyek. __DIR__, direktori dari file saat ini, menghilangkan tebak-tebakan itu:

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

Tulis setiap include sebagai __DIR__ . '/relative/path.php'. Direktori kerja bergantung pada cara script dijalankan (web server, cron job, command line dari folder lain), tetapi __DIR__ tidak pernah berubah.

Jangan pernah meng-include file yang dinamai oleh pengguna

Router pertama yang umum dibuat membaca nama halaman dari URL: include $_GET['page'] . '.php';. Cara itu membiarkan pengunjung memilih file mana di server yang dijalankan, misalnya ?page=../../config (local file inclusion), dan dengan pengaturan lama bahkan file dari server lain. Sebagai gantinya, petakan nama yang diizinkan ke file. Jalankan blok ini lalu klik link-linknya: setiap klik menjalankan script lagi dengan $_GET['page'] yang berbeda.

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

Hanya tiga nama di $pages yang bisa sampai ke require; link ../secret mendapat halaman "Not found". Cara membaca nilai request dengan aman dibahas di $_GET dan$_POST.