Include Statement

The include statement is a PHP language construct that evaluates and incorporates the contents of a specified file into the execution flow of the calling script. When invoked, the PHP parser temporarily suspends execution of the current script, reads the target file, executes its contents within the current scope, and then resumes execution of the original script.

Syntax

Because include is a special language construct and not a standard built-in function, parentheses are optional around the file path argument.

// Without parentheses (preferred standard)
include 'filepath.php';

// With parentheses
include('filepath.php');

// Assigning a return value from an included file
$result = include 'filepath.php';

Error Handling and Execution Flow

The defining characteristic of include is its error-handling behavior. If the PHP engine cannot locate or access the specified file, it emits an E_WARNING level error. The critical technical distinction is that script execution continues after this warning. This contrasts with the require construct, which emits a fatal E_COMPILE_ERROR and immediately halts execution.

Scope and Context

Code within the included file inherits the variable scope of the exact line where the include statement occurs, but this inheritance applies strictly to variables.

• Variables: If include is called from within a function or method, the variables defined in the included file will be restricted to that local scope. If called in the global scope, the variables become available globally.
• Functions, Classes, Interfaces, and Traits: Regardless of where the include statement is executed (even within a local function scope), any functions, classes, interfaces, or traits defined within the included file are placed in the global scope, unless the included file contains a namespace declaration. If a namespace is declared, those structures are placed within that specific namespace. In either case, they become globally accessible, bypassing the local scope of the calling function.
• Magic Constants: Constants like __FILE__ and __DIR__ resolve to the included file’s path and directory, not the calling file’s context.

Parsing Context

When an include statement is executed, the PHP parser drops out of PHP mode and enters HTML mode at the beginning of the target file. Therefore, any PHP code within the included file must be explicitly enclosed within valid PHP tags (<?php ... ?>). If the tags are omitted, the engine treats the file’s contents as plain text/HTML and outputs it directly to the buffer.

Path Resolution

PHP resolves the file path provided to the include statement using the following hierarchy:

1. Absolute/Relative Paths: If the path is absolute (e.g., /var/www/file.php) or explicitly relative (e.g., ./file.php or ../file.php), PHP looks only at that specific location.
2. include_path Directive: If only a filename or an implicit relative path is provided (e.g., inc/file.php), PHP searches the directories defined in the include_path configuration directive in php.ini.
3. Calling Script Directory: If the file is not found in the include_path, PHP checks the directory of the script that executed the include statement.
4. Current Working Directory: Finally, PHP checks the current working directory of the execution process before failing and emitting an E_WARNING.

Remote File Inclusion

If the allow_url_include directive is enabled in the PHP configuration (php.ini), the include construct can fetch and execute files from remote sources using URL wrappers (such as http:// or ftp://). However, the allow_url_include feature has been deprecated since PHP 7.4. When a remote file is included, PHP downloads the payload and executes any valid PHP code contained within it, provided the remote server does not parse the file before transmitting it. This distinguishes include from standard file-reading functions, as it actively evaluates the retrieved stream rather than just reading it as a string.

Return Values

By default, the include construct returns 1 upon successful execution and FALSE on failure. However, the included file can use the return statement to terminate its own execution and pass a specific value back to the calling script. If a return statement is encountered inside the included file, the include expression evaluates to that returned value.

Master PHP with Deep Grasping Methodology!

Learn More