include and require

While a program fits on one screen, one file is enough for it. A real website is thousands of lines: functions for users, for orders, for emails. In a single file you can't find anything, the same way you can't find the right chapter in a ten-thousand-page book.

Picture a library. Each file of the program is a separate book on its own subject: one holds the greeting functions, another the site settings.

When the program needs a book, it asks: "take this one off the shelf and read it right now". In PHP that request is written with the require statement.

Let's put a function into a separate file, greet.php:

<?php

function greet(string $name): string
{
    return 'Hello, ' . $name . '!';
}

Next to it, in the same folder, sits main.php, which uses this function:

<?php

require 'greet.php';

echo greet('Anna'), "\n";
echo greet('Oleg'), "\n";

Let's run the main file:

$ php main.php
Hello, Anna!
Hello, Oleg!

Let's go through it step by step:

1. PHP runs main.php from top to bottom and reaches the line require 'greet.php';.
2. It finds greet.php in the same folder and runs the whole file: the function greet gets declared.
3. PHP comes back to main.php at the next line, and the function greet is already known.
4. The two calls to greet print two greetings.

The file runs in place

require runs the included file as if its text stood in place of that line. Three things follow from this:

• the file's functions and classes are available after the require line;
• the variables the file creates land in the same scope where the require stands;
• the file's code outside functions runs at once: an echo in it prints at the moment of inclusion.

A path without a folder, like 'greet.php', is looked up in the folder the script was started from and in the folder of the file that holds the require. To make the path independent of where the script was started from, write require __DIR__ . '/greet.php';. The constant __DIR__ holds the folder of the current file.

A file can return a value

A file can end with a return statement, and then require returns that value, like a function. Settings are usually kept this way: the file config.php returns an array.

<?php

return [
    'site' => 'Bookshelf',
    'perPage' => 20,
];

The main file takes it into a variable: $config = require 'config.php';. After that $config['site'] is the string 'Bookshelf', and $config['perPage'] is the number 20. The settings sit in one place, and to change them you don't have to search the whole program.

When the file is missing

The include statement pulls a file in the same way as require. There is one difference: what happens when the file is not there.

include: a warning

The line include 'menu.php'; without a menu.php file gives two warnings, and the script goes on:

Warning: include(menu.php): Failed to open stream: No such file or directory
Warning: include(): Failed opening 'menu.php' for inclusion

The page still gets built, only without the menu.

require: an Error

The line require 'footer.php'; without the file gives the same warning and then throws an Error:

Warning: require(footer.php): Failed to open stream: No such file or directory
Fatal error: Uncaught Error: Failed opening required 'footer.php'

As you already know, an uncaught Error stops the script at that line. You can catch it with try and catch (Error $e). Before PHP 8 this was a fatal error that could not be caught at all.

Which statement should you pick? require is for files the program makes no sense without: settings, functions, classes. include is rare: it fits where a page can survive losing a piece.

How include differs from require is a common interview question.

require_once

A large program pulls in the same files from different places. require_once remembers which files have already run and skips the same file the second time. It compares the full path to the file, so 'greet.php' and __DIR__ . '/greet.php' are the same file for it.

Pull in a file with functions or classes through require_once. Keep the plain require for files like config.php that return a value: a repeated require_once would return true instead of the array.

Common mistake

A file was pulled in twice with a plain require. Here the library picture stops working: you can read a book twice, but you cannot run a file with a function twice. Say mailer.php also starts with the line require 'greet.php'; for its emails:

<?php

require 'greet.php';
require 'mailer.php'; // ✗

echo greet('Anna'), "\n";

Fatal error: Cannot redeclare function greet()

PHP runs greet.php a second time, now from inside mailer.php, and tries to declare the function greet again. A function cannot be declared twice, so the script stops. The fix is require_once in both files: then the second inclusion is skipped.

Key points

• require runs a file in place of its line: the file's functions, classes and variables are available afterwards.
• A file can return a value with return: settings are kept this way, $config = require 'config.php';.
• Without the file, include gives a warning and goes on, while require throws an Error and stops the script.
• require_once runs a file only once—this is how files with functions and classes are pulled in.