Require Once Statement

The require_once statement is a PHP language construct that includes and evaluates a specified file during script execution, with the strict condition that the file is parsed only once per execution cycle. If the specified file cannot be found or read, the Zend Engine triggers a fatal E_COMPILE_ERROR and immediately halts script execution.

Syntax

Because require_once is a language construct and not a standard function, parentheses are optional. Omitting them is the standard convention.

// Standard syntax
require_once 'path/to/file.php';

// Valid, but generally discouraged syntax
require_once('path/to/file.php');

// Assigning a return value from the included file
$result = require_once 'path/to/file.php';

Execution Mechanics

Internal Registry Checking When require_once is invoked, PHP resolves the absolute path of the target file (resolving any symbolic links) and checks it against its internal registry of previously included files. This registry can be inspected during runtime using the get_included_files() function. If the resolved path exists in this registry, PHP bypasses the inclusion process entirely.

Path Resolution Path resolution behavior depends strictly on the format of the provided string. If an absolute path or an explicit relative path (starting with ./ or ../) is provided, PHP resolves the path directly and completely bypasses the include_path directive. The include_path directive is only searched when an unqualified relative path is provided (e.g., require_once 'file.php';). If an unqualified file is not found within the include_path, PHP falls back to checking the directory of the calling script, followed by the current working directory.

Scope Inheritance The code within the included file inherits the variable scope of the exact line where the require_once statement occurs. Any variables available at that line in the calling file will be available within the included file. However, functions and classes defined in the included file are placed into the global scope.

Return Values

The require_once construct evaluates to a specific value based on the execution state:

• Successful First Inclusion: Returns 1 by default.
• Explicit Return: If the included file contains a return statement in its global scope, require_once evaluates to that specific returned value.
• Subsequent Calls: If the file has already been included earlier in the execution lifecycle, require_once returns boolean true and does not re-execute the file.

Compilation Overhead

Because require_once must perform absolute path resolution and check the internal inclusion registry to guarantee uniqueness, it incurs a marginal performance overhead compared to the standard require statement. The engine must ensure that two different relative paths pointing to the same physical file are recognized as identical to prevent duplicate compilation.

Master PHP with Deep Grasping Methodology!

Learn More