PHP Reference ยท Language Constructs and Statements
PHP include and require
Reference for PHP include, include_once, require and require_once: load other files, return values, path resolution and how failures differ.
include and require read another PHP file and run it at the point where the statement appears. They are how you split a program into several files: shared functions, configuration, class definitions and templates.
The two differ only in how they fail. If the file cannot be loaded, require stops the script with a fatal error, while include raises a warning and the script goes on. The _once variants skip the file if it has already been loaded, which prevents "cannot redeclare" errors.
require __DIR__ . '/vendor/autoload.php'; $config = include 'config.php'; // the file can `return` a value
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.
A failed require cannot be demonstrated in a script that has to keep running, because it stops the program:
require '/no/such/file.php'; // Fatal error: Uncaught Error is NOT thrown; PHP reports "Failed opening required" (E_COMPILE_ERROR) echo "never printed";
Syntax
include expression; include_once expression; require expression; require_once expression;
| Name | Description |
|---|---|
expression |
A string with the path of the file. Parentheses are allowed but not needed. |
Return value: whatever the file returns with return; 1 if the file ran and returned nothing; false when include or include_once fails. include_once and require_once return true if the file was already loaded.
Errors: a missing file gives an E_WARNING with include and a fatal E_COMPILE_ERROR with require (it is not a catchable exception, and the script ends). A parse error in the loaded file throws ParseError.
Usage notes
- Same scope. The loaded file shares the variable scope of the line that included it. Inside a function, it sees that function's local variables. A
returnat the top level of the file ends only that file. - Path resolution. A path starting with
/or a drive letter is absolute../and../are relative to the current working directory. Anything else is searched ininclude_pathfirst, then in the calling script's directory. Build paths from__DIR__to avoid surprises. - Use
requirefor essentials. A missing class file or configuration should stop the program. Useincludefor optional parts, such as an optional template. _oncecosts a lookup. It resolves the real path to compare with loaded files. For classes, an autoloader (see Autoloading) is better than manyrequire_oncelines.- Never include user input.
include $_GET['page']allows local and sometimes remote file inclusion attacks. Map allowed names to fixed files instead. - Leading output. Text outside
<?php ... ?>tags in the included file is sent to the output, so stray whitespace before<?phpshows up. This is why many files omit the closing tag. - Templates. Including a file that mixes HTML and PHP is the oldest templating method; see PHP tags and embedding.
- Remote files. Including URLs needs
allow_url_include, which is off by default and should stay off.